API authentication

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:

Scope	Description
`read_only`	Read access to all data endpoints. Cannot modify data, trigger syncs, or create resources.
`full_access`	Full 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

curl -X POST \
  -H "X-API-Key: bb_your_key" \
  -H "Content-Type: application/json" \
  -d '{}' \
  http://localhost:8080/api/v1/sync

Authentication errors

Condition	Status	Code
`X-API-Key` header missing	`401`	`MISSING_API_KEY`
Key does not start with `bb_`	`401`	`INVALID_API_KEY`
Key does not match any active key	`401`	`INVALID_API_KEY`
Key has been revoked	`401`	`REVOKED_API_KEY`
Key scope is insufficient for the endpoint	`403`	`FORBIDDEN`

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.

Device-code flow (CLI and headless agents)

The Breadbox CLI uses a device-code grant so an operator on one machine can mint an API key for a client on another — without ever copying a long-lived secret onto the second machine through an unverified channel. The browser approval lives on the trusted device; the remote machine only ever sees the issued bb_ key. The flow is exposed at two unauthenticated REST endpoints:

Method	Path	Description
`POST`	`/api/v1/auth/device-code`	Initiates a session. Returns a `device_code`, a `user_code` to display to the operator, a `verification_url` to open in a browser, and a poll `interval`.
`POST`	`/api/v1/auth/device-code/poll`	Polls with the `device_code`. Returns `authorization_pending` until the operator approves in their browser; returns the issued `bb_` API key on success; returns `expired` after the TTL.

The standard CLI invocation:

# On the remote machine (no key yet)
breadbox auth login --host https://breadbox.example.com
# CLI prints: "Open https://breadbox.example.com/auth/device on the host you trust,
#              enter code: ABCD-1234"
# Operator approves in their browser; the CLI saves the key to ~/.config/breadbox/hosts.toml

Pass --token bb_… to skip the device flow entirely (paste-mode) when an operator has already minted a key on the server side. See the CLI authentication guide for the full flow including auth bootstrap (local-only key mint) and BREADBOX_TOKEN env override.

Headless bootstrap

A single unauthenticated endpoint helps remote agents confirm they’re talking to a live Breadbox before they have a key:

Method	Path	Description
`GET`	`/api/v1/headless/bootstrap`	Returns the server version, public configuration (which providers are configured, whether the dashboard is enabled), and the device-code endpoints to use next. No `X-API-Key` required.

Use it as a smoke test from a breadbox-cli build (breadbox doctor calls it automatically).

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.

Overview

Endpoints

API authentication

Getting an API key

Key format

Key scopes

Passing the key

Authentication errors

Device-code flow (CLI and headless agents)

Headless bootstrap

Key management best practices

​Getting an API key

​Key format

​Key scopes

​Passing the key

​Authentication errors

​Device-code flow (CLI and headless agents)

​Headless bootstrap

​Key management best practices

Getting an API key

Key format

Key scopes

Passing the key

Authentication errors

Device-code flow (CLI and headless agents)

Headless bootstrap

Key management best practices