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
• a class: PUBLISHABLE for browser embeds or SECRET for server-side use
• one or more permissions
• allowed origins
• active or blocked status
• expiration metadata when set through the API
• a configurable requests-per-minute limit (default 60)

Supported permissions are:

Important Behavior

• raw keys are only shown once when created
• blocked keys stay listed but cannot authenticate requests
• new allowed origins are normalized to HTTP(S) origins and matched exactly 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

Key Classes And Browser Origins

Use PUBLISHABLE keys in widgets and frontend SDKs. Create SECRET keys for server-side integrations; never put a secret key in an embed snippet, browser code, or a public URL. Class comes from stored metadata, not the key prefix. Create a replacement key to change class.

The three /v1/conversations read endpoints require a SECRET key with conversations:read. The chat permission alone does not grant transcript access.

Allowed origins are a browser hint, not authentication. Non-browser clients can forge Origin and x-kravos-parent-origin. New publishable keys require at least one HTTP(S) origin. Existing keys with empty lists keep working and allow any origin; the dashboard warns about them so you can add origins without silently breaking existing integrations. Secret server keys may have an empty origin list.

Source DELETE requires the explicit destructive grant sources:delete, matching MCP. Normal ingest/ingest.write grants and * do not imply that destructive grant.

Rate Limits

Each authenticated request consumes the key's stored rateLimit in a rolling 60-second window. The same key shares one budget across the REST API, first-party MCP, web v1, and SDK init; changing transport does not reset it. Requests over budget return HTTP 429 with a Retry-After header in seconds. Wait that long before retrying.

Only a Redis availability failure bypasses the limiter, with a server warning. Invalid limits and configuration or script errors do not bypass it. Other authentication and permission checks still apply during an outage.

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 PUBLISHABLE 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

1. create a PUBLISHABLE key with chat only
2. add at least one allowed browser origin
3. copy the raw key immediately because it is only shown once
4. test the integration before sharing the key with teammates

Rotate a key safely

1. create the replacement key first
2. update the integration to use the new key
3. confirm traffic is arriving on the new key
4. 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.