The REST API authenticates with a secret key sent as a bearer token. Keys are created by workspace owners and admins in API & Keys in the dashboard.
Authorization: Bearer sk_live_key_…Keys belong to an environment
The sandbox and production are separate systems. A key created in the sandbox dashboard only works against the sandbox API, and a production key only against production. Start with a sandbox key.
Create a key
Each key has:
- a name so you can recognise it later
- a bot restriction: one bot, or the whole workspace (an explicit choice that includes bots you create later)
- one or more scopes
- an expiry of 30, 90 or 365 days
- optionally, the audiences it may request
The secret is shown once. Only a SHA-256 hash of a random 256-bit value is stored, so a lost key cannot be recovered: create a new one.
Scopes
| Scope | Allows |
|---|---|
bots:read | List the bots the key can use and read their settings. |
documents:read | List documents and check ingestion status. |
documents:write | Upload and delete documents. |
chat:write | Ask questions and fetch suggested questions. |
knowledge:read | Search for passages. Existing keys do not gain this scope automatically. |
Grant the smallest set a service needs. A server that only answers questions needs chat:write and nothing else. A request without the required scope is rejected, and the reference lists the scope for every endpoint.
Account settings, bot creation and editing, key management, analytics and conversation listings are dashboard-only and always reject API keys.
Not found, not forbidden
A bot, document or conversation that belongs to another workspace, or that this key is not allowed to use, returns 404 rather than 403. Other tenants' identifiers are indistinguishable from ones that do not exist.
Rotate and revoke
Rotating a key issues a new secret and keeps the key's identity, so conversations it created remain continuable. Revoking stops it immediately. Rotate on a schedule and whenever a secret may have leaked. Key listings show metadata only: prefix, scopes, last used and expiry.
Publishable keys for the widget
The website widget uses a different, public key (pk_…) that is safe to include in page source. It can only chat with one bot, and only from the domains you allow. The SDK refuses pk_ keys, and the REST API does not accept them.