Authentication

curl https://reygrid.com/api/v1/validate \
  -H "Authorization: Bearer $REYGRID_API_KEY"

import os, httpx

res = httpx.get(
    "https://reygrid.com/api/v1/validate",
    headers={"Authorization": f"Bearer {os.environ['REYGRID_API_KEY']}"},
)
print(res.json())

const res = await fetch("https://reygrid.com/api/v1/validate", {
  headers: { Authorization: `Bearer ${process.env.REYGRID_API_KEY}` },
});
console.log(await res.json());

{
  "success": true,
  "valid": true,
  "usage": { "total": 1337, "quotaLimit": 5000 }
}

curl https://reygrid.com/api/v1/validate \
  -H "Authorization: Bearer $REYGRID_API_KEY"

import os, httpx

res = httpx.get(
    "https://reygrid.com/api/v1/validate",
    headers={"Authorization": f"Bearer {os.environ['REYGRID_API_KEY']}"},
)
print(res.json())

const res = await fetch("https://reygrid.com/api/v1/validate", {
  headers: { Authorization: `Bearer ${process.env.REYGRID_API_KEY}` },
});
console.log(await res.json());

{
  "success": true,
  "valid": true,
  "usage": { "total": 1337, "quotaLimit": 5000 }
}

How it works

The API uses a Bearer token. The token is your ReyGrid API key, sent in the Authorization header of every authenticated request.

Item	Value
Scheme	HTTP `bearer` (`bearerFormat: API-Key`)
Header	`Authorization: Bearer <API_KEY>`
Where	Request header only

Every endpoint except GET /ping requires authentication.

curl https://reygrid.com/api/v1/validate \
  -H "Authorization: Bearer $REYGRID_API_KEY"

import os, httpx

res = httpx.get(
    "https://reygrid.com/api/v1/validate",
    headers={"Authorization": f"Bearer {os.environ['REYGRID_API_KEY']}"},
)
print(res.json())

const res = await fetch("https://reygrid.com/api/v1/validate", {
  headers: { Authorization: `Bearer ${process.env.REYGRID_API_KEY}` },
});
console.log(await res.json());

{
  "success": true,
  "valid": true,
  "usage": { "total": 1337, "quotaLimit": 5000 }
}

Validate a key

GET /validate confirms a key works and returns usage.total and usage.quotaLimit. See the reference.

Authentication errors

A missing or invalid key returns 401 with the flat AuthErrorResponse shape:

{
  "error": "Unauthorized",
  "code": "AUTH_REQUIRED"
}

401 bodies are not wrapped like other errors ({ "success": false, "error": { … } }). Check the HTTP status first, then parse accordingly. See Errors.

Security considerations

Keep keys on the server. Don’t ship them in browser or mobile code.
Load keys from environment variables or a secrets manager. Don’t commit them.
Avoid logging the Authorization header.
Always use HTTPS. The base URL is https://reygrid.com/api/v1.
If you build per-user experiences, authenticate users in your backend and call ReyGrid from there. See Persistent conversations.

The OpenAPI specification documents only the Bearer API key. It does not describe key creation, rotation, or scopes.

Introduction

Guides

Webhooks

Health & keys

Account

Chat

Agents

Knowledge

Search

Conversations

Messages

Tool calls

How it works

Validate a key

Authentication errors

Security considerations

​How it works

​Validate a key

​Authentication errors

​Security considerations

How it works

Validate a key

Authentication errors

Security considerations