Skip to main content
Every request to the Breadbox REST API must include a valid API key. Keys are created from the admin dashboard, scoped to control what operations a client can perform, and passed as a request header on every call. Breadbox never stores the full plaintext key — the key is shown once at creation and then hashed.

​
Getting an API key

Create API keys from the admin dashboard under Settings → API Keys. Give each key a descriptive name so you can identify it later (for example, "Home Assistant" or "Monthly report script"). The full plaintext key is displayed exactly once when you create it — copy it to a safe location before closing the dialog. For detailed configuration steps, see the API keys configuration guide.

​
Key format

All Breadbox API keys begin with the bb_ prefix followed by 32 cryptographically random bytes encoded in base62: 
bb_4xK9mZ2nQpR7sT1vW3yA5bC8dE6fG0hJqLnPuVw
The total length is approximately 46 characters. Any string that does not start with bb_ is immediately rejected.

​
Key scopes

Each key is assigned one of two scopes at creation time:
ScopeDescription
read_onlyRead access to all data endpoints. Cannot modify data, trigger syncs, or create resources.
full_accessFull read and write access. Required for any endpoint marked Write in this documentation.
Choose the narrowest scope that meets your use case. AI agents that only query transaction history should use read_only keys. Agents or scripts that create rules, categorize transactions, or trigger syncs need full_access.

​
Passing the key

Include the key in the X-API-Key HTTP header on every request: 
X-API-Key: bb_your_api_key_here

curl -H "X-API-Key: bb_your_key" \
  http://localhost:8080/api/v1/accounts

​
Authentication errors

ScenarioHTTP StatusError Code
X-API-Key header missing401 UnauthorizedMISSING_API_KEY
Key does not start with bb_401 UnauthorizedINVALID_API_KEY
Key does not match any active key401 UnauthorizedINVALID_API_KEY
Key has been revoked401 UnauthorizedREVOKED_API_KEY
Key scope is insufficient for the endpoint403 ForbiddenFORBIDDEN
All authentication errors use the standard error envelope: 
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "X-API-Key header is required."
  }
}
A 401 response means the key itself is invalid or absent. A 403 response means the key is valid but does not have the required scope — for example, a read_only key attempting a write operation.

​
Key management best practices

  • One key per client. Assign a separate key to each application or script that calls the API. This lets you revoke a single key without disrupting other clients.
  • Use read_only by default. Grant full_access only when the client genuinely needs to write data.
  • Rotate keys periodically. Create a new key, update the client, then revoke the old key from the dashboard.
  • Never expose keys in client-side code or version control. Treat API keys with the same care as passwords. If a key is compromised, revoke it immediately from Settings → API Keys.
  • Store keys in environment variables or a secrets manager rather than hardcoding them in configuration files.