Create API Key

{
  "name": "Production API Key",
  "role": "agent_manager",
  "expires_at": "2025-12-31T23:59:59Z"
}

{
  "raw_key": "bk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key": {
    "key_id": "apikey_a1b2c3d4e5f6",
    "name": "Production API Key",
    "role": "agent_manager",
    "prefix": "bk_live_xxxx",
    "client_id": "org_abc123",
    "user_id": "user_def456",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": null,
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

POST

api

api-keys

{
  "name": "Production API Key",
  "role": "agent_manager",
  "expires_at": "2025-12-31T23:59:59Z"
}

{
  "raw_key": "bk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key": {
    "key_id": "apikey_a1b2c3d4e5f6",
    "name": "Production API Key",
    "role": "agent_manager",
    "prefix": "bk_live_xxxx",
    "client_id": "org_abc123",
    "user_id": "user_def456",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": null,
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

Create a new API key for programmatic access to the Butter AI API. API keys are scoped to both the creating user and the current organization.

The raw API key is only shown once in the response. Store it securely as it cannot be retrieved later.

Headers

string

required

Bearer token from Cognito authentication (JWT).

string

required

The organization ID.

string

required

Must be application/json.

Permissions

Only admin and agent_manager roles can create API keys.
You cannot create a key with a higher role than your own.

Request Body

string

required

A human-readable name for the API key (1-100 characters).

string

required

The role assigned to this API key. Must be one of: admin, agent_manager, user.

string

Optional ISO 8601 UTC datetime when the key should expire. If not provided, the key never expires.

Response

string

The full API key - shown once only. Store this securely.

object

The API key metadata.

Show properties

string

Unique key identifier.

string

The name of the API key.

string

The role assigned to this key.

string

The first 12 characters of the key (for identification).

string

The organization ID this key belongs to.

string

The user ID who created this key.

string

Current status (active or revoked).

string

ISO 8601 timestamp of creation.

string

ISO 8601 timestamp of last usage (null if never used).

string

ISO 8601 timestamp of expiration (null if never expires).

{
  "name": "Production API Key",
  "role": "agent_manager",
  "expires_at": "2025-12-31T23:59:59Z"
}

{
  "raw_key": "bk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key": {
    "key_id": "apikey_a1b2c3d4e5f6",
    "name": "Production API Key",
    "role": "agent_manager",
    "prefix": "bk_live_xxxx",
    "client_id": "org_abc123",
    "user_id": "user_def456",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": null,
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

Error Responses

403 Forbidden

Returned when the caller does not have permission to create API keys or is trying to create a key with a higher role than their own.

{
  "detail": "Only admins and agent managers can create API keys"
}

400 Bad Request

Returned when the role is invalid.

{
  "detail": "role must be one of: admin, agent_manager, user"
}

List API Keys Revoke API Key

Introduction

Agents

Phone Numbers

Calls

Knowledge Base

Tools

Organizations

Billing

Analytics

Preview & Voice Selection

Integrations

API Keys

Headers

Permissions

Request Body

Response

Error Responses

​Headers

​Permissions

​Request Body

​Response

​Error Responses

Headers

Permissions

Request Body

Response

Error Responses