API keys and access
Create scoped organisation keys and distinguish private server access from restricted browser sessions.
An organisation owner or administrator creates keys under Integrations → API keys, when API access is available on the organisation's plan. Keys belong to that organisation and expire or can be revoked.
Choose a key type
| Type | Intended use | Restrictions |
|---|---|---|
Private, sgs_ | Your trusted backend. | Selected scopes; keep the value off browsers and public repositories. |
Public, sgp_ | A browser voice integration. | Exact origins and explicit assistant IDs are required for call creation. |
Create a named key with the smallest required scope set, expiry and request limit. Copy the displayed key into the intended application's configuration. A key cannot grant access beyond its organisation, plan or current owner permissions.
Available scopes
| Scope | Endpoint or capability |
|---|---|
agents:read | GET /api/v1/agents; public keys receive their permitted assistant subset. |
sdk:authorize | POST /api/v1/sdk/authorize; checks a saved assistant or permitted transient descriptor. |
calls:create | Create a browser audio session. Public keys also manage only their own token-bound sessions. |
calls:read | Read organisation call state, metrics and retained outputs with a private key. |
calls:control | End a call or approve its pending action with a private key. |
integrations:read | Server-side integration access; private keys only. |
Public keys cannot receive calls:read, calls:control or integrations:read. Their session requests use calls:create and the returned X-Call-Token.
Authenticate requests
Authorization: Bearer YOUR_API_KEYA public browser key also requires the exact allowed Origin. An origin has a scheme, host and optional port, without a path or wildcard. Add each deployment origin explicitly.
An SDK authorization check does not start a call or bypass voice configuration/publication. The calls API starts an actual session; the browser SDK handles audio and controls for you.
Handle expiry and limits
Revoked, expired or invalid keys receive 401 responses. Missing scopes or disallowed browser origins receive 403. Request-rate limits return 429 with Retry-After: 60. Fix access failures before retrying, and replace expiring keys deliberately.