Skip to main content
POST
Create an API key

Authorizations

Authorization
string
header
required

Use a workspace API key in the Authorization header. Keys use pk_live_<key_id> for production and pk_test<key_id>_ for test mode.

Headers

Idempotency-Key
string

Optional retry key for safely replaying create requests. Reusing the same key with a different request body returns 409.

Required string length: 8 - 255
Example:

"8db8e596-7c1a-4fd5-a728-4d6c99f4e66b"

Body

application/json
name
string
required

Human-readable label for the key.

Example:

"CI deploy"

scopes
enum<string>[]
required
Minimum array length: 1

Workspace API key permission scope.

Available options:
customers:read,
customers:write,
conversations:read,
conversations:write,
messages:write,
attachments:read,
attachments:write,
webhooks:manage,
realtime:read,
ai:use,
keys:manage,
help:read,
help:drafts:write
environment
enum<string>

Defaults to the calling key's environment.

Available options:
live,
test

Response

Created API key with its raw secret (shown once).

A newly created key. The secret is shown once and never again.

id
string
required
Example:

"key_o5mj4q7beg32vkjcd76a37t5zy"

name
string
required
environment
enum<string>
required
Available options:
live,
test
scopes
enum<string>[]
required

Workspace API key permission scope.

Available options:
customers:read,
customers:write,
conversations:read,
conversations:write,
messages:write,
attachments:read,
attachments:write,
webhooks:manage,
realtime:read,
ai:use,
keys:manage,
help:read,
help:drafts:write
display
string
required

Masked key preview safe to display.

Example:

"pk_test_key...cret"

secret
string
required

The raw API key. Store it now; it cannot be retrieved later.

Example:

"pk_test_key_o5mj4q7beg32vkjcd76a37t5zy_abcdefghijklmnopqrstuvwxyz234567"