Authentication and API keys

Send a key

Every API request authenticates with a BreachLine API key. Keys start with bl_live_. Send the key in either header; both are accepted on every public endpoint.

X-API-Key

X-API-Key headerCopy

GET /api/v1/llm/v1/models HTTP/1.1
Host: api.breachline.io
X-API-Key: bl_live_YOUR_KEY

Authorization

Bearer tokenCopy

GET /api/v1/llm/v1/models HTTP/1.1
Host: api.breachline.io
Authorization: Bearer bl_live_YOUR_KEY

The console authenticates with a short-lived session token sent the same way (Authorization: Bearer). A few account operations accept only a session token; the reference marks them.

Authentication fails closed: a missing, malformed, expired or revoked credential gets 401, and no request is ever served without a verified principal. A valid key whose account is suspended gets 403 (Account has been suspended), and so does a key whose account was deactivated for inactivity; signing in to the console reactivates an inactive account.

Create a key

Create keys in the console under Settings, API & Developer, or with POST /api/v1/keys/create from an interactive session.

• Keys cannot create keys. A request authenticated with an API key gets 403. Key creation always comes from a signed-in person.
• Recent sign-in required. The session must be under five minutes old, or the request must include the account password. Otherwise the response is 428 Precondition Required, which the console turns into a password prompt.
• Shown once. The plaintext key appears only in the creation response, sent with Cache-Control: no-store. Afterwards only its prefix is visible.
• Out-of-band notice. Creating a key sends a security notification to the account owner, because a key is a credential that works without a second factor.

Scopes

A key can do only what its scopes allow. Grant the smallest set that does the job.

Scope	Grants
llm:access	Every LLM API endpoint, including models, embeddings and rerank.
llm:chat	Chat completions, Responses and Messages, plus Batches and batch files (with an organization-bound user).
llm:embeddings	Embeddings.
llm:batch	Batches and batch files (with an organization-bound user).
keys:read	Listing your keys with GET /api/v1/keys/list.
keys:revoke	Revoking keys.

When you create a key without scopes, a standard key gets llm:access, llm:chat and cli:knowledge:read. You can always grant llm:* scopes. Any other scope, including that default cli:knowledge:read, must be one you hold yourself in your organization; asking for more returns 403 and names the scopes you cannot grant.

The console’s Access scopes picker follows the same rule: it preselects llm:access, llm:chat and cli:knowledge:read, and offers further optional scopes such as llm:embeddings. Scopes you do not hold are shown but cannot be selected. Scopes the picker does not offer, such as llm:batch, keys:read or keys:revoke, can be requested through POST /api/v1/keys/create.

Member scopes on the Platform API

Platform endpoints such as usage, settings, audit logs and integrations are gated by member scopes: the permissions an organization owner gives each person, for example usage:read, settings:write, audit:read or integrations:notify. A call made with an API key is checked against the member scopes of the person who owns the key. The key’s own scopes do not narrow these checks, so a key reaches whatever its owner’s member scopes allow on these endpoints. For automation, use a key that belongs to a member whose scopes cover only what the job needs. See Scopes and roles.

Limits

Limit	Value
Active keys per user	10
Key creations per user per hour	5
Maximum lifetime	365 days by default. A longer or omitted expiry is capped.
Key name	100 characters

Rotate and revoke

• Rotate with POST /api/v1/keys/refresh/{key_id} and your account password. The old secret stops working at once and the new one is returned once. Rotation, like creation, needs an interactive session.
• Revoke in the console or with DELETE /api/v1/keys/{key_id}. Revocation is immediate.
• List with GET /api/v1/keys/list to see each key’s prefix, scopes, expiry and last use.

Rotate keys on a schedule, when people leave your team and whenever a key may have been exposed.

How keys are stored

BreachLine stores only a SHA-256 hash of each key, never the key itself. The console and the API show a short prefix (bl_live_ plus four characters) so you can tell keys apart. Because the secret cannot be recovered, a lost key must be rotated or replaced.

Keys in tools and CI

• The CLI reads BREACHLINE_API_KEY for non-interactive sign-in. See CLI configuration.
• In CI, store the key as a masked secret and scope it to llm:access and llm:chat unless the job needs more.
• Give each environment and each service its own key, so you can revoke one without affecting the others.