API Key Management
Each agent has three keys with different scopes and trust levels. Using the right key in the right place is the most important step in keeping your integration secure.
The three keys
| Prefix | Name | Where it goes | Keep secret? |
|---|---|---|---|
agt_ | Public agent key | Widget data-agent-id attribute, client-side SDK. Included in HTML served to browsers. | No - it is intentionally public. |
sk_ | Client API key | Your server when creating signed sessions. Never sent to the browser. | Yes - treat like a password. |
ck_ | Management key | Server-to-server admin calls: creating agents, uploading documents, managing databases via the REST API. | Yes - treat like a password. |
What each key can and cannot do
| Operation | agt_ | sk_ | ck_ |
|---|---|---|---|
| Load agent widget config | Yes | Yes | Yes |
| Create anonymous session | Yes | Yes | No |
| Create signed session | No | Yes | No |
| Send messages | No (session token required) | No (session token required) | No |
| Upload documents | No | No | Yes |
| Create / update / delete agents | No | No | Yes |
| Manage databases | No | No | Yes |
Storing keys safely
Store sk_ and ck_ keys in environment variables or a secrets manager - never in source code, client bundles, or public repositories. Reference them at runtime on your server only.
Rotating a key
In the console open the agent, go to the API Keys tab, and click Rotate next to the key you want to replace. A new key is issued immediately. The old key continues working for a short grace period to allow for a zero-downtime rollover - update your server environment and then revoke the old key.
Revoking a key
Click Revoke on the key in the console. Revocation is immediate - all requests using that key will be rejected with HTTP 401 from that point on. Use this if a key is exposed or you suspect it has been compromised.
If a key is leaked
Revoke the compromised key immediately, then rotate to a new one. Review your session and action logs for any anomalous calls made with the exposed key. If the leaked key was a ck_ management key, audit recent document uploads and agent configuration changes.