Skip to main content
POST

Authorizations

Authorization
string
header
required

Pass the API key in the Authorization header, You need to put Token keyword before the API key. e.g. 'Authorization: Token '

Query Parameters

projectId
string<uuid>
required

ID of the project. With an API key, it must be the key's own project.

Example:

"fbb9e8b2-2dbb-40f9-a051-9404624e3247"

Body

application/json
name
string
required

Key name, unique in the project.

Minimum string length: 1
Example:

"Backend server"

kind
enum<string>
default:LEGACY

SECRET (sk_...): for servers. The value is shown once, in the response that creates or rotates the key; requests that carry an Origin header (browsers) are refused. PUBLIC (pk_...): for web pages and apps. It can only create call tokens (POST /v1/voice-agents/call-token), for one environment, and its value can be read again at any time. LEGACY: the older kind, whose key ID is also its value. New legacy keys are being retired: when they are turned off, creating one returns LegacyApiKeysRetired.

Available options:
LEGACY,
PUBLIC,
SECRET
Example:

"SECRET"

type
enum<string>
default:ROOT

ROOT: everything your role in the project allows (scopes ["*"]). SCOPED: only the scopes you list, and never more than your role allows. Public keys are always SCOPED with ["agents:call"].

Available options:
ROOT,
SCOPED
Example:

"ROOT"

scopes
string[]

What a SCOPED key may do. Each item is a preset name, resource:action, resource:* (every action on a resource) or *:action (an action on every resource); presets are expanded when saved. Scopes your role does not have are refused (403). Presets: calls_only, campaigns_only, transcription_only, tts_only, ai_content_only, translate_only, realtime_only (see GET /v1/projects/api-keys/scope-presets). Resources and their actions: agents: create, read, update, delete, export, import, call; knowledge_base: create, read, update, delete, cancel; policies, guardrails, functions_macros: create, read, update, delete, assign; tools, phone_numbers, voices, secrets, voice_overs, transcription: create, read, update, delete; call_history: read, delete, export, monitor; outbound_calls: create, read, update, delete, launch, stop; project: read, update, delete, deactivate; members: read, invite, update, delete; billing: read, update; statistics: read; translate: create, read; tts: create, read, delete; realtime: create, read. GET /v1/projects/api-keys/scopes-schema lists the ones your role allows. Required when type is SCOPED. Ignored for public keys.

Minimum string length: 1
Example:
environment
enum<string>

Public keys only, and required for them: the environment their call tokens run.

Available options:
dev,
staging,
prod
Example:

"prod"

allowedDomains
string[]

Hostnames the key may be used from, such as example.com or *.example.com (any subdomain). No protocol, at most 255 characters each. Empty: any domain. A public key checks them against the Origin header.

Required string length: 1 - 255
Example:
agentIds
string<uuid>[]

Agents the key may create call tokens for (agents of this project). Empty or omitted: every agent.

Example:
expiredAt
number | null

Expiry as a Unix timestamp in milliseconds, in the future. The key works until the end of that day. Omitted or null: never expires.

Example:

1830297600000

Response

API key created

success
boolean
Example:

true

message
string
Example:

"success"

data
object

An API key. Never contains a secret key's value, except secret in the response that creates or rotates it.