Admin Dashboard: API Keys

API keys authenticate programmatic access to the SyntheticBrew Engine. Each key can be scoped to specific capabilities, allowing you to follow the principle of least privilege. Keys are created through the dashboard and can be revoked at any time.

Creating an API key

Click “Create API Key” on the API Keys page.
Give it a descriptive name (e.g., “chatbot-frontend”, “ci-cd-pipeline”).
Select the scopes this key needs (see table below).
Click “Create” — the key is shown once. Copy it immediately.

Available scopes

Scope	Description
`chat`	Send messages to a schema (POST /schemas/{name}/chat). The most common scope for client applications.
`tasks`	CRUD operations on /tasks. Create, list, cancel tasks and provide input.
`agents:read`	Read-only access to agent configurations (GET /agents).
`config`	Reload, export, and import configuration. Useful for CI/CD pipelines.
`admin`	Full access to all endpoints including API key management and settings.

Connect a coding agent (MCP provisioning token)

On SyntheticBrew Cloud you don’t need a token here at all — the agent signs in through your browser over OAuth (claude mcp login, or Cursor/VS Code prompt automatically). See Connect a Coding Agent (MCP).

The Connect a coding agent button on this page mints a scoped token for the cases OAuth doesn’t cover — a self-hosted engine (which has no OAuth server) or a headless/CI integration:

The default scope is provision — create and read agents, models, and MCP servers. This covers the full provisioning flow. Listing the available MCP tools (tools/list) requires a token with a provision scope.
Tick Allow destructive operations (manage) to also grant the manage scope, which permits deleting and overwriting existing configuration. Leave it off unless the agent needs it.
As with every key, the token (prefix bb_) is shown once.

The token is passed with --header "Authorization: Bearer <token>" (Claude Code) or the equivalent headers block for other agents — see the self-hosted section of Connect a Coding Agent (MCP).

Usage examples

# Use an API key in requests
curl http://localhost:8443/api/v1/agents \
  -H "Authorization: Bearer bb_your_api_token"

# Example: key with chat + tasks scopes
# Can call: POST /schemas/{name}/chat, GET/POST/DELETE /tasks
# Cannot call: /config/reload, API key management, settings

# Example: key with config scope only (CI/CD)
curl -X POST http://localhost:8443/api/v1/config/reload \
  -H "Authorization: Bearer bb_cicd_deploy_token"

Revoking a key

Click the “Revoke” button next to any key in the list. Revocation is immediate — any request using that key will receive a 401 Unauthorized response. Revocation is logged in the Audit Log.