Skip to main content
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

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

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"
}
Returned when the role is invalid.
{
  "detail": "role must be one of: admin, agent_manager, user"
}