API Keys
API keys authorize backend access for widgets, SDK clients, custom tools, and external integrations.
API Keys
API keys authorize backend access for widgets, SDK clients, custom tools, and external integrations.
What A Key Can Control
Each key can include:
- a name
- one or more permissions
- allowed origins
- active or blocked status
- expiration metadata when set through the API
Supported permissions are:
| Permission | Use it for |
|---|---|
| chat | Chat and streaming endpoints |
| retrieve | Retrieval-only queries and some voice tool flows |
| ingest | Programmatic content ingestion |
Internal managed permission
Voice skill fetching can use a managed internal skill_fetch permission. User-created dashboard keys
expose the public chat, retrieve, and ingest permissions.
Important Behavior
- raw keys are only shown once when created
- blocked keys stay listed but cannot authenticate requests
- allowed origins are exact URL matches when configured
- key cards show current requests per minute and last-used time
- the system may create bootstrap or managed voice keys when voice tooling needs retrieval or skill access
Good Key Hygiene
- create separate keys for separate use cases
- limit permissions to the minimum required
- set allowed origins for browser-based use where possible
- rotate keys when ownership changes
- delete old keys instead of leaving them dormant forever
Typical Examples
Widget or frontend integration
Use a key with only the permissions the integration actually needs, plus allowed origins.
Retrieval-only internal search
Use a retrieve-only key.
Content ingestion workflow
Use an ingest key that is not shared with chat clients.
Common Workflows
Create a chat key for a frontend
- create a key with
chatonly - add allowed origins if the browser will call the endpoint directly
- copy the raw key immediately because it is only shown once
- test the integration before sharing the key with teammates
Rotate a key safely
- create the replacement key first
- update the integration to use the new key
- confirm traffic is arriving on the new key
- block or delete the old key
Block a suspicious key
If a key should stop working immediately, block it instead of waiting for a later cleanup pass. You can investigate first and delete it after you know it is no longer needed.
Related Docs
API Reference
Interactive endpoint docs for chat, retrieval, and source management.
Tools
Enable built-in tools and create custom HTTP tools for your agent.
Skills
Reusable instructions can use managed keys for private voice skill fetching.
MCP Servers
Connect GitHub, Slack, Notion, databases, and external systems.