> ## Documentation Index
> Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage API keys

> Generate scoped API keys to authenticate REST API and MCP calls, control access with read-only or full-access scopes, and revoke keys you no longer need.

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](/api/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

<Steps>
  <Step title="Open API Keys">
    In the admin dashboard, navigate to **Settings → API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create API Key**. Enter a descriptive name — for example, `Claude Agent` or `Home Budget Script` — then click **Generate Key**.
  </Step>

  <Step title="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.

    ```text theme={null}
    bb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5
    ```

    After you leave this page, only the key's prefix (`bb_a1b2c3`) is visible in the dashboard.
  </Step>
</Steps>

<Note>
  API keys are managed exclusively from the admin dashboard.
</Note>

<Warning>
  Breadbox stores only a hash of your key. If you lose it, you must revoke the old key and generate a new one.
</Warning>

## Key format

Every API key starts with the `bb_` prefix followed by a random string of characters, for example:

```text theme={null}
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:

```bash theme={null}
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:

```text theme={null}
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.