Admin Dashboard: API Keys

API Keys creates persistent bb_ credentials for programs that cannot use an interactive browser flow. For Claude Code, Codex, Cursor, and VS Code, use OAuth onboarding first so no secret is pasted into a prompt or config.

When a manual key is appropriate

Use a scoped key for CI, server-to-server jobs, controlled scripts, widget chat, or an MCP client environment where OAuth is unsuitable. Do not use an Admin key when Chat, Tasks, or read-only access is sufficient.

Create a key

Open API Keys and choose Generate New Token.
Enter a recognizable integration name.
Select the minimum scopes: Chat, Tasks, Agents Read/Write, Models Read/Write, MCP Read/Write, Config, or Admin.
Generate and copy the full token immediately.

The token is shown once. The table later shows name, scopes, creation date, and last-used date, never the secret value.

Available scopes

Scope	Typical use
Chat	Send messages to any chat-enabled schema.
Tasks	Create, read, update, and cancel tasks.
Agents Read / Write	Inspect agents or change agent configuration.
Models Read / Write	Inspect models or change provider configuration.
MCP Read / Write	Inspect or change MCP server configuration.
Config	Reload, import, and export supported configuration.
Admin	Full access. Reserve it for tightly controlled administration.

Read and write are separate for agents, models, and MCP servers. A key may carry more than one scope, but selecting Admin makes narrower selections unnecessary.

curl https://YOUR_SYNTHETICBREW_ORIGIN/api/v1/schemas/support/chat \
  -H "Authorization: Bearer bb_REDACTED" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

Store the key in a secret manager or protected environment variable:

export SYNTHETICBREW_TOKEN="bb_REDACTED"
curl "$SYNTHETICBREW_URL/api/v1/agents" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN"

Do not place the key in a URL, checked-in profile, prompt, screenshot, browser-visible log, or shell history shared with other users.

Coding-agent authority

OAuth requests either provision or manage. Provision can create and update resources. Manage includes destructive authority. Replacing an existing Knowledge Graph bundle removes records omitted from the payload, so admin_import_knowledge_graph requires both replace_existing: true and manage authority. Incremental entity upserts remain the safer provisioning path.

For a headless coding agent, expand Connecting a coding agent manually (per-client instructions). The guided panel creates a provision token by default and generates the configuration for Claude Code, Cursor, VS Code, OpenAI Codex, or a generic MCP client. Enable Allow destructive operations (manage) only when required.

Revoke and rotate

Choose Revoke when a key is exposed, unused, or replaced. Update the consumer first when continuous availability matters, verify the new key’s Last Used value, then revoke the old one.

Revocation is immediate for subsequent requests. If a revoked key still appears to work, confirm that the consumer is not using a different credential or an existing browser/OAuth session.