Skip to main content
API keys authenticate requests to Breadbox’s REST API and MCP server. Every external client — whether a curl command, a custom script, or an AI agent — must present a valid API key in the X-API-Key header. You manage keys from the admin dashboard and can revoke them at any time.

​
Scopes

Each key has one of two scopes:
ScopePermissions
full_accessRead and write — can query transactions, update categories, create rules, and submit agent reports
read_onlyRead only — can query accounts, transactions, and balances, but cannot modify any data
Use read_only keys for AI agents unless the agent specifically needs to categorize transactions or create rules. This limits the blast radius if a key is ever exposed.

​
Generate a key from the dashboard

1

Open API Keys

In the admin dashboard, navigate to Settings → API Keys.
2

Create a new key

Click Create API Key. Enter a descriptive name — for example, Claude Agent or Home Budget Script — then click Generate Key.
3

Copy the key immediately

The full key is displayed once and never stored in plaintext. Copy it now and save it in a password manager or secrets vault.
bb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5
After you leave this page, only the key’s prefix (bb_a1b2c3) is visible in the dashboard.
Breadbox stores only a hash of your key. If you lose it, you must revoke the old key and generate a new one.

​
Key format

Every API key starts with the bb_ prefix followed by a random string of characters, for example: 
bb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5
The prefix makes it easy to identify Breadbox keys in logs and secrets managers, and to set up secret scanning rules in your version control system.

​
Use a key in requests

Pass the key in the X-API-Key header on every request: 
curl -H "X-API-Key: bb_your_api_key" \
  "http://localhost:8080/api/v1/transactions?limit=10"
For MCP over HTTP, pass the same header when connecting your agent: 
URL: https://your-host/mcp
Header: X-API-Key: bb_your_api_key

​
Create a key from the CLI

If you prefer to create keys without the dashboard — for example, in a setup script — use the api-keys subcommand: 
breadbox api-keys create "My Agent"
The command prints the full key once. Save it before the terminal session closes.

​
Revoke a key

To revoke a key, go to Settings → API Keys in the dashboard, find the key by its name or prefix, and click Revoke. Revocation takes effect immediately — any in-flight request using that key returns a 403 Forbidden error.

​
Best practices

  • Use a separate key for each client or agent so you can revoke access for one without affecting others.
  • Prefer read_only keys for AI agents unless they need to write data.
  • Rotate keys periodically, especially after personnel changes or suspected exposure.
  • Never commit a key to version control. If you accidentally push a key, revoke it immediately and generate a replacement.