API Keys and Service Keys

Ortavox uses two types of API keys to authenticate requests.

Key Types

Type	Prefix	Usage
Private	`sk_live_...`	Server-side only — full API access, never expose in browser
Public	`pk_live_...`	Client-side safe — restricted to specific agents and origins

Creating an API Key

$ POST /v1/api-keys
$ Authorization: Bearer <your-token>
$ 
$ {
>   "name": "Production API Key",
>   "tag": "private",
>   "permissions": ["read:agents", "create:calls"],
>   "restrictions": {
>     "allowedAgentsIds": ["agent-uuid-1", "agent-uuid-2"],
>     "allowedOrigins": ["https://yourapp.com"]
>   },
>   "expiresAt": "2026-12-31T23:59:59Z"
> }

Parameters

Property	Type	Required	Description
`name`	`string`	✅	Human-readable label for the key
`tag`	`string`	❌	`private` (default) or `public`
`permissions`	`array`	❌	Default: `["read:agents", "create:calls"]`
`restrictions.allowedAgentsIds`	`array`	❌	Restrict key to specific agent IDs
`restrictions.allowedOrigins`	`array`	❌	Restrict key to specific origins (CORS)
`expiresAt`	`datetime`	❌	Optional expiry date for the key

Important: The full key value (sk_live_...) is only shown once at creation time. Store it securely immediately.

Using a Key

Pass your API key as a Bearer token or as the x-api-key header:

$ # As Bearer token
$ Authorization: Bearer sk_live_yourkey
$ 
$ # As header
$ x-api-key: sk_live_yourkey