Skip to main content
POST
Create an API key

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Headers

Idempotency-Key
string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

Required string length: 1 - 255
X-Test-Mode
enum<string>

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Available options:
true,
false

Body

application/json
name
string
required

Human-readable label shown in the dashboard. Not used for authentication.

Required string length: 1 - 100
type
enum<string>
default:secret

secret = server-only dv_*_sk_* key; public = browser-safe pk_* key for the embed SDK.

Available options:
secret,
public
scopes
string[]

API key permission scopes (e.g. messages:write). At least one scope is required for keys minted after 2026-08-01; empty-scope keys are deprecated and treated as least-privilege (viewer) / will be rejected after the grandfather deadline.

mode
enum<string>
default:live

test keys never deliver messages and never bill; useful for CI/staging.

Available options:
live,
test
expiresIn
enum<string>
default:never
Available options:
never,
30d,
90d,
1y
allowed_ips
string[]

Optional IP/CIDR allowlist. Auth middleware rejects requests from a non-allowlisted source.

Maximum array length: 50
Required string length: 1 - 64

Response

API key created — store the key value now

API key created — store the key value now

data
object
meta
object