Skip to main content
POST
Create API Key

Headers

string
required
Your API key for authentication. Restricted keys cannot create keys, so use a full-access key.

Body

string
required
The kind of key to create. Use org for an organization key. Restricted keys require org.
string
The ID of your organization. Required when type is org. The key is created for the organization your credentials belong to, and you must be an owner or admin of it.
string
A label for the key, up to 64 characters. Omit it or pass null to leave the key unnamed.
string[]
The permissions for a restricted key. Omit it to create a full-access key.When present, it must be a non-empty list of the permissions in Restricted keys, which also says what each one allows.Restricted key creation is rolling out by organization. When it is not enabled for yours, the request returns 403 with the error SCOPED_KEYS_NOT_ENABLED. When your organization runs on a pinned deployment, the request returns 409 with the error RESTRICTED_KEYS_UNAVAILABLE. See Pinned deployments. When your organization has no full-access key, the request returns 409 with the error NO_FULL_ACCESS_KEY. See Keep one full-access key.

Response

object
The created key.
string
The full API key. This is the only time the full value is returned, so store it securely. Restricted keys start with org_s_.
string | null
The key’s name, or null if it has none.
string[] | null
The permissions the key holds, with implied permissions included. null means the key has full access.
null | array
null on success, or a list of errors.

Restricted keys

A restricted key can only call the endpoints its permissions cover. Use one when you hand a key to a contractor, a CI job, or an integration that needs part of your account and not all of it. Permissions are named by resource and action. Every resource has a read permission. Most also have a write permission, or an action permission for work that spends credits or sends messages. The table lists what each permission opens for a restricted key, and what stays closed to every restricted key no matter which permissions it holds. Personas, phone numbers, tools, alerts, and automations have no permissions yet. Their responses can carry stored credentials (tool headers, webhook authentication, imported-number credentials, alert delivery inputs, and pipeline webhook configuration), so they stay full-access only until their reads hide those values.

Permissions that include others

A write permission includes its resource’s read permission. The action permissions evals:run, sms:send, tests:run, and voices:generate include their resource’s read permission too. calls:create includes calls:stop, so a key can end the calls it places. The scopes field in the response and in List API Keys shows the full set. The dashboard’s key list hides a permission when another permission on the same key includes it.

Names shared with the hosted MCP server

calls:create, calls:stop, and evals:run are also OAuth scopes for the hosted MCP server. Placing and stopping calls mean the same thing on both. For a key, evals:run opens creating, editing, and deleting saved judge templates, call sets, and setups, and starting a run still needs a full-access key. For an MCP app it runs evaluations.

Permissions you can grant

Key creation accepts only permissions that open something today, which is every permission in the table. Any other value returns 400 with the error INVALID_SCOPES, and the message lists the accepted set. Every restricted key can also read your account details (GET /v1/me), the voice catalogue (GET /v1/voices), and the list and details of your knowledge bases without their description or metadata (GET /v1/knowledge and GET /v1/knowledge/:id), since pathways reference voices and knowledge bases. The model list (GET /v1/models) needs no key.

Requests outside a key’s permissions

A request to an endpoint the key’s permissions do not cover returns 403 with a WWW-Authenticate: Bearer error="insufficient_scope" header. The body names the permission that would allow the request when one exists.
403 Response
New endpoints are denied to restricted keys until they are assigned a permission.

What restricted keys cannot do

  • Create, list, rename, or delete API keys.
  • Use the hosted MCP server at /v1/mcp.
  • Exchange the key for a session token or another key.

Restricted keys belong to the organization

A restricted key keeps working when the member who created it leaves the organization, changes role, or is banned. The key list shows who created each key so an admin can review it, and an admin revokes a key with Delete API Key. Someone who leaves with a copy of a key keeps its access until an admin deletes it, so revoke keys as part of offboarding.

Pinned deployments

Restricted keys are not available to organizations on a pinned deployment. When restricted key creation is enabled for your organization, creating one returns 409 with the error RESTRICTED_KEYS_UNAVAILABLE, and the dashboard shows Restricted disabled with an upgrade explanation. When the rollout is not enabled, the dashboard hides Restricted and creation returns 403 with SCOPED_KEYS_NOT_ENABLED. Full-access keys work as usual.

Keep one full-access key

Your organization must keep at least one full-access key while it has restricted keys. Live calls and dashboard sessions depend on it. Delete API Key refuses to delete the last one, and creating a restricted key while your organization has none returns 409 with the error NO_FULL_ACCESS_KEY.

Docs for agents: llms.txt