Scopes

API key scope reference.

API keys use scopes to control access. Assign scopes when creating a key to limit what it can do.

Available Scopes

Scope	Access
`user:read`	View profile, credits balance, list API keys
`user:write`	Update profile, create and delete API keys
`kb:read`	List and get workspaces, documents, and search
`kb:write`	Create/delete workspaces, upload/delete documents
`chat:read`	List and get chat sessions and messages
`chat:write`	Create sessions, send messages, query agent

Scope Requirements by Endpoint

Each endpoint documents its required scope. A request with an API key missing the required scope returns 403 Forbidden.

Read Scopes

user:read — GET /v1/user/me, GET /v1/user/api-keys
kb:read — GET /v1/kb/workspaces, GET /v1/kb/documents, POST /v1/kb/query
chat:read — GET /v1/chat/sessions, GET /v1/chat/sessions/:id/messages

Write Scopes

user:write — POST /v1/user/api-keys, DELETE /v1/user/api-keys/:id
kb:write — POST /v1/kb/workspaces, DELETE /v1/kb/workspaces/:id, POST /upload/init, POST /upload/complete
chat:write — POST /v1/chat/sessions, POST /agent

Rate Limits

Request rate limits by plan tier.

Errors

HTTP error codes and response format.

On this page

Available Scopes Scope Requirements by Endpoint Read Scopes Write Scopes