API Keys

What API keys are for

API keys (they start with brk_) authenticate requests to the BrainRoad platform:

• The REST API: agent status, start/stop, propose work for review, read billing
• The OpenAI-compatible chat API (/v1/chat/completions)
• Event streaming (SSE)
• The public MCP endpoint for Claude Code, Codex, and other MCP clients

They are not the same as your AI provider keys (Anthropic, OpenAI, and so on, managed in Settings) and not the same as your Gateway Token (which authenticates directly to your helper’s runtime).

Creating a key

1. Go to Dashboard → API. The page is titled “Developer Access”. You can create keys even while your helper is stopped.
2. In the “AI connections and API keys” card, enter a name (for example, “Claude desktop” or “Monitoring script”).
3. Pick an access mode:
   • Brain + Inbox connector (recommended): a restricted preset bound to your helper. This is what you want for connecting Claude Code, Codex, or another MCP client. You can adjust the individual scope checkboxes.
   • Full REST API access (advanced): a legacy unscoped mode for trusted REST automation. Keys in this mode are not accepted by the public MCP endpoint.
4. Click Create, then copy the key immediately. It is shown exactly once. BrainRoad stores only a hash and the first 12 characters as a display prefix.

After creating a connector key, the page shows the MCP endpoint plus ready-made Claude Code and Codex setup snippets with a built-in connection test.

Scopes

Each scoped key carries an explicit list of what it may do:

Scope	Allows
agent:read	Read helper status
agent:write	Start, stop, update a helper
agent:provision	Provision or remove a helper
brain:read	Search and read the Business Brain
brain:write	Add notes to the Business Brain
brain:ask	Ask questions answered from the Brain
triage:read	Read the review queue (Inbox) and work record
triage:propose	Propose new cards for your review
chat:write	Use the chat completions API
activity:read	Subscribe to the activity event stream
billing:read	Read plan and subscription status (read-only)

Two things no key can do, by design:

• Approve review cards. Approval is a human step in the dashboard. A triage:approve scope exists in the vocabulary but is reserved and not honored by any endpoint today.
• Admin actions. API keys never carry admin rights.

A key can be bound to one helper at creation (the recommended connector preset does this). Binding is identity, not extra power: it tells the MCP server which helper the key speaks for, so the external tool never needs internal IDs.

Managing keys

• Up to 10 active keys per account.
• Each key shows its name, prefix, and scopes on the API page.
• Revoke any key instantly. Revoked keys are rejected right away, and open event streams close within about 30 seconds.
• Create a separate key per system so you can revoke one without breaking the others.

Using a key

Pass it as a Bearer token:

curl https://app.brainroad.com/api/v1/agent/status \
  -H "Authorization: Bearer brk_your_key_here"

Requests are limited to 120 per minute per key on /api/v1/. Missing scopes return 403.