Authentication

BrightBean uses HTTP bearer-token authentication. The same key works for the REST API, the MCP server, and the SDKs/CLI.

Key format

API keys look like:

bb_d3a7e9f1c4b08125ab6c91f037d8e2b4

That’s a bb_ prefix followed by 32 hex characters (16 bytes of entropy). Keys are issued in app.brightbean.xyz under API Keys. You see the full key exactly once; we store a salted hash, not the key itself, so we cannot recover it later.

Sending the key

REST

Send the key in the Authorization header:

Authorization: Bearer bb_d3a7e9f1c4b08125ab6c91f037d8e2b4

MCP

The MCP server at api.brightbean.xyz/mcp accepts the same key via the same Authorization: Bearer … header. Most MCP clients accept this via a config block — see MCP client setup.

SDKs

All three SDKs (Python, TypeScript, CLI) read the BRIGHTBEAN_API_KEY environment variable by default. You can also pass the key explicitly to the constructor:

client = BrightBean(api_key="bb_…")

const client = new BrightBean({ apiKey: "bb_…" });

The CLI additionally supports a per-machine profile config at ~/.brightbean/config (INI format) so you can switch between development and production keys without touching env vars. See the CLI page.

Rotation

You can have multiple keys active per account. To rotate:

1. Create a new key in API Keys.
2. Roll your environment variables / secret managers over to the new key.
3. Revoke the old key from the same page.

Revoked keys 401 immediately on the next request.

What gets logged

Every authenticated request records: request ID, account ID, endpoint or MCP tool name, credits debited, response status, and a hash of the request body. We do not log the request body itself, response body, or your API key. You can review recent activity in the dashboard under Usage → Recent calls.

Security guidelines

Errors

See Errors for the full error envelope.