API keys and security
Create, restrict, and manage Developer API keys securely.
Create an API key
- Open the Admin Panel and select the assistant.
- Go to Developer API.
- Select Create API Key, enter a name, and choose the required scopes.
- Copy the
ac_…key to a server-side secret manager.
The full key is displayed once. Each key belongs to one assistant, so runtime requests do not pass an assistant_id. Keys end with a checksum, so a mistyped or truncated key is rejected immediately with INVALID_API_KEY, and leaked keys can be recognized by secret scanners.
Scopes
| Scope | Allows |
|---|---|
chat:write | Create JSON or SSE chat responses. |
files:write | Upload files for an external user. |
conversations:read | Read conversations and message lists. |
feedback:write | Submit message feedback. |
voice:connect | Create a voice session and connect over WebSocket. |
users:delete | Permanently erase an end user's data. |
Grant only required scopes. Use separate keys for each application and environment; add an IP allowlist when your backend has fixed outbound IPs. Rate limits are shared across all keys of an assistant.
Billing and user data
- Chat and voice consume credits from the assistant's billing owner.
- Models and features are limited by the owner's plan.
- Conversations, files, and memory are isolated by assistant and
external_user_id. - Keep
external_user_idstable and do not use an email address, phone number, or secret.
Preview does not have a separate sandbox. Staging requests may create real data and consume credits. Use a separate staging assistant and API key.
Protect API keys
- Send keys only over HTTPS using
Authorization: Bearer .... - Never place a key in a browser, mobile application, URL, source control, or logs.
- Your backend must authenticate an end user before mapping them to
external_user_id. - For browser voice, the backend creates a session and returns only
token,expires_at, andwebsocket_urlto the client. - For mobile and desktop applications, use a backend intermediary or OAuth Authorization Code with PKCE to issue a token for each user or installation. Keychain/Keystore can protect a per-installation token or private key at rest; it cannot make a shared embedded Developer API key confidential.
Edit, replace, or revoke a key
Edit changes a key's name or IP allowlist in place; the secret keeps working. Clearing the allowlist allows any IP. Scopes and expiry cannot be edited: create a new key to change them.
Rotate issues a replacement key with the same name, scopes, IP allowlist, and expiry, then retires the old key when you choose:
| Option | Use when |
|---|---|
| Immediately | The key may be exposed. Requests using the old key fail at once. |
| In 1 hour, 24 hours, or 7 days | Planned rotation. The old key keeps working until the deadline, then returns API_KEY_EXPIRED. |
For a planned rotation, deploy the replacement to every instance and send a test request before the grace period ends.
Revoke blocks the key immediately and cannot be undone. Delete removes the key from the list; it stops working at once. Creating, editing, rotating, revoking, and deleting keys are recorded in an audit log with the acting admin.