Create an API key

POST

/api/api-keys

• Production

Creates a new API key with the specified scopes and optional restrictions. The full key is returned only in this response — store it securely, as it cannot be retrieved later. The key follows the format ‘sf_live_v1_…’ and should be passed in the Authorization header as ‘Bearer sf_live_v1_…’.

Authorizations

• bearerAuth

Request Body

object

name

required

A human-readable name to identify this key’s purpose.

string

>= 1 characters <= 255 characters

Example

CRM Integration - Production

scopes

required

Permission scopes for this key. At least one scope is required.

Array<string>

>= 1 items

Example

[
  "conversations:read",
  "contacts:read",
  "kb:read"
]

brandId

Restrict this key to a specific brand. Omit for unrestricted access.

string format: uuid

workspaceId

Restrict this key to a specific workspace. Omit for unrestricted access.

string format: uuid

expiresAt

When the key should expire. Omit for a key that never expires.

string format: date-time

Example

2027-01-01T00:00:00.000Z

Responses

200

The API key was created. The response includes the full key — this is the only time it will be available.

Response returned when a new API key is created. This is the only time the full key value is available — store it securely, as it cannot be retrieved later.

object

id

required

Unique identifier for the new API key.

string format: uuid

Example

ak1a2b3c-5678-9abc-def0-1234567890ab

name

required

The name assigned to the key.

string

Example

CRM Integration - Production

keyPrefix

required

The prefix portion of the key for future identification.

string

Example

sf_live_v1_a3Bf

key

required

The full API key. This is only returned once at creation time. Store it in a secure location — it cannot be retrieved again. Use this value in the Authorization header as ‘Bearer sf_live_v1_…’.

string

Example

sf_live_v1_a3BfX9kLmN2pQrStUvWxYz...

scopes

required

Permission scopes granted to this key.

Array<string>

Example

[
  "conversations:read",
  "contacts:read"
]

createdAt

required

Timestamp when the key was created.

string format: date-time

Example

2026-03-27T12:00:00.000Z

422

Validation error. For example, no scopes were provided or the name is too long.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found