Skip to content
OrbContext
19 pages

Build

Authentication

Secret keys, scopes, bot restrictions, expiry and rotation.

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.

Request header
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

ScopeAllows
bots:readList the bots the key can use and read their settings.
documents:readList documents and check ingestion status.
documents:writeUpload and delete documents.
chat:writeAsk questions and fetch suggested questions.
knowledge:readSearch 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.