Create and manage API keys

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. For the key format, rate-limit behavior, and server-side error responses, see the Authentication page in the API reference.

Scopes

Each key has one of two scopes:

Scope	Permissions
`full_access`	Read and write — can query transactions, update categories, create rules, and submit agent reports
`read_only`	Read 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

Open API Keys

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

Create a new key

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

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.

API keys are managed exclusively from the admin 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

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.

​Scopes

​Generate a key from the dashboard

​Key format

​Use a key in requests

​Revoke a key

​Best practices

Scopes

Generate a key from the dashboard

Key format

Use a key in requests

Revoke a key

Best practices