Skip to main content
The ChatGrid API supports two authentication methods: API keys (recommended for server-to-server) and Supabase JWTs (used by the web app).

​
API keys

API keys are the recommended way to authenticate. They start with the cgk_ prefix and are passed in the Authorization header. 
curl https://api.chatgrid.ai/v1/boards \
  -H "Authorization: Bearer cgk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

​
Creating an API key

You can create API keys from the dashboard or via the API itself (requires admin scope): 
curl -X POST https://api.chatgrid.ai/v1/me/api-keys \
  -H "Authorization: Bearer cgk_live_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline", "scopes": ["read", "write"]}'
The full key is returned only once in the raw_key field. Store it securely — it cannot be retrieved again.

​
Key security

  • Keys are stored as SHA-256 hashes. ChatGrid never stores your raw key.
  • Revoked or expired keys are rejected immediately.
  • Each key’s last_used_at is tracked for auditing.

​
Scopes

Each API key has one or more scopes that control what it can access:
ScopePermissions
readList and retrieve resources (boards, chats, messages, nodes, etc.)
writeCreate, update, and delete resources. Includes everything in read.
adminManage API keys and access admin-only endpoints. Includes everything in write.
If a request requires a scope your key does not have, you receive a 403 Forbidden: 
{
  "object": "error",
  "status": 403,
  "code": "forbidden",
  "message": "Missing required scope: write"
}

​
Scope requirements by endpoint

MethodScope required
GET (list/retrieve)read
POST, PATCH, DELETE (mutate)write
GET /me/api-keys, POST /me/api-keys, DELETE /me/api-keys/:idadmin

​
JWT authentication

The ChatGrid web app authenticates with Supabase JWTs. If you are building a frontend integration, you can pass the user’s Supabase access token: 
curl https://api.chatgrid.ai/v1/boards \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
JWT-authenticated requests automatically have read, write, and admin scopes. Rate limits differ from API key limits (200 req/min for JWTs).

​
Error responses

StatusCodeMeaning
401unauthorizedMissing or invalid token
401unauthorizedAPI key has been revoked
401unauthorizedAPI key has expired
403forbiddenToken lacks the required scope