Skip to main content
Each scope is a door on your key: app, user, conversation, or message — open only what you need.
The user JWT does not use these scopes. It authenticates the client app on /v1/chat/* (REST) and the WebSocket. The API Key is for your backend.

​
How to send the key

Or x-api-key. The key belongs to one workspace. Do not send x-workspace-id on v1.

​
Common combinations

App setup

chat:apps:create, chat:apps:manage, chat:apps:list

Identity

chat:users

Backend conversations

chat:conversations:read, chat:conversations:write

Messages

chat:messages:send, chat:messages:read
An empty scope list at creation = ADMIN access. Restrict in production.

​
Available scopes

List and get Chat Apps.
Create a Chat App. The response includes the signing secret.
Update name, origins, JWT flags, and rotate the secret.
Remove a Chat App (soft delete).
User upsert, JWT issue, and team agents.
List and get workspace conversations.
Create conversations, members, roles, join, and soft delete.
Send a message (1 CHAT_MESSAGE credit).
List messages and mark read.
Soft-delete a message.

​
JWT vs API Key

​
Common errors

  • 401 — missing key/JWT, rotated secret, revoked jti (CHAT_INVALID_TOKEN)
  • 403 — missing scope, origin not allowed, or JWT create with flags off (CHAT_CLIENT_CREATE_DISABLED)
  • 402 — WORKSPACE_BLOCKED, INSUFFICIENT_CREDITS, or key spend limit
  • 409 — CHAT_DIRECT_EXISTS

​
Next steps