Create API Key

POST /api/api-keys

Request

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

Response

{
  "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

Authorization · string · required

Bearer token from Cognito authentication (JWT).

X-Organization-Id · string · required

The organization ID.

Content-Type · 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

name · string · required

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

role · string · required

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

expires_at · string

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

Response

raw_key · string

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

key · object

The API key metadata.

Show properties

key_id · string

Unique key identifier.

name · string

The name of the API key.

role · string

The role assigned to this key.

prefix · string

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

client_id · string

The organization ID this key belongs to.

user_id · string

The user ID who created this key.

status · string

Current status (active or revoked).

created_at · string

ISO 8601 timestamp of creation.

last_used_at · string

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

expires_at · string

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

Request

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

Response

{
  "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"
}