Skip to main content

Authentication

Every request carries an API key. There are no other credentials — no OAuth flow, no session, no signing.

The two header forms​

They are equivalent. Use whichever your HTTP client makes easier.

curl https://api.botlobby.ai/v1/users/credits \
  -H "Authorization: Bearer bl_live_..."
curl https://api.botlobby.ai/v1/users/credits \
  -H "X-API-Key: bl_live_..."

If both are present, the key is resolved the same way either path.

Creating a key​

Settings → API Keys in the web app. API access is a top-tier plan feature, so the option is gated on your plan.

When you create one you choose its scopes. The default is read and generate — enough to create content and render video, nothing destructive.

The key is shown once​

Only a SHA-256 hash of the key is stored. The plaintext is returned exactly once, at creation, and cannot be recovered afterwards. Lose it and you mint a new key and revoke the old one.

Every key starts bl_live_. That prefix is deliberate: it makes a leaked key recognisable in logs and scanners, and it lets the server tell an API key from a session token in the same header.

Scopes are fixed for a key's life​

You choose them at creation and they never change. To adjust what a key can do, create a new one with the scopes you want and revoke the old one.

Revoking​

Revocation is immediate — the next request with that key gets 401. The key list shows last_used_at for each one, which is the quickest way to spot a key nothing is using any more.

Keeping keys safe​

  • Server-side only. A key in client-side JavaScript, a mobile app bundle, or a public repository is a key someone else has. There is no browser-safe variant.
  • One key per integration. Separate keys mean you can revoke one without breaking everything else, and last_used_at tells you which is which.
  • Grant the narrowest scope set that works. Most integrations never need delete.
  • Rotate on exposure. If a key reaches a log aggregator, a screenshot, or a CI output, treat it as compromised and revoke it.

Checking a key​

GET /v1/api-keys/introspect needs no scope and tells you whether a key is live and what it can do:

curl -s https://api.botlobby.ai/v1/api-keys/introspect \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"
{
  "active": true,
  "subject": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "scopes": ["read", "generate"]
}

It is the right first call when debugging: it separates "the key is wrong" from "the request is wrong".