{
"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"
}
}
API Keys
Create API Key
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
adminandagent_managerroles 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
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
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
400 Bad Request
Returned when the role is invalid.
{
"detail": "role must be one of: admin, agent_manager, user"
}