Authentication

Every Developer API request must include a cb_live_ token in the Authorization header:

Authorization: Bearer cb_live_4f8a3b9c0d1e2f5...

Tokens are issued from the panel — see API tokens for the UI flow.

Token format

cb_live_<32-char-url-safe-base64>

The prefix lets you spot tokens at a glance in logs and secret scanners. There is no cb_test_ prefix today — use a dedicated organization for staging if you need isolation.

Errors

Status	`detail.error`	Cause
`401`	`Missing Authorization header`	No header sent
`401`	`Invalid Authorization format`	Header not `Bearer <token>`
`401`	`Invalid token format`	Token doesn’t start with `cb_live_`
`401`	`Invalid token`	Token revoked or never existed
`403`	`Token is disabled`	Toggled off in panel
`403`	`Token expired`	Past `expires_at`
`403`	`Token lacks 'mcp_query' permission`	Permission not granted at creation
`409`	`llm_key_required`	The organization has no LLM provider key configured

Stable identity per token

The Developer API derives a stable user identity from each token, so audit logs group queries together per token. To track multiple end-users separately, issue one token per end-user (recommended for partner integrations) — see API tokens → pass-through prefix.

Rotating

POST /tokens/{id}/regenerate from the panel issues a new secret and invalidates the old one immediately. Old requests in flight return 401. There is no overlap window.

Storing

Treat cb_live_ tokens like database passwords:

Environment variables on the host, not config files in git.
Secret manager in production (AWS Secrets Manager, HashiCorp Vault, etc).
Restrict access to deploy users only.

Permissions reference

{
  "mcp_query": true,        // POST /api/v1/chat/completions, GET /api/v1/projects, GET /api/v1/usage
  "mcp_admin": false,       // reserved
  "sources_read": true,     // GET /api/v1/sources
  "sources_write": false,   // PATCH /api/v1/sources/* (future)
  "agents_run": false       // reserved
}

Most tokens only need mcp_query. Toggle the rest off to enforce least privilege.

Rate limits

Each token carries per_minute / daily / monthly request limits (set when you create it, defaults 60 / 1000 / 10000). They apply across all /api/v1/* endpoints. When a limit is hit the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{ "detail": { "error": "rate_limit_exceeded", "period": "per_minute", "limit": 60, "retry_after_seconds": 37 } }

Honor the Retry-After header (seconds) and retry with exponential backoff. Rejected requests don’t count against the bucket.

Developer API

Endpoints

Webhooks

Token format

Errors

Stable identity per token

Rotating

Storing

Permissions reference

Rate limits

​Token format

​Errors

​Stable identity per token

​Rotating

​Storing

​Permissions reference

​Rate limits

Token format

Errors

Stable identity per token

Rotating

Storing

Permissions reference

Rate limits