Backbone LabDocs
Get started

Authentication

The Backbone Lab API authenticates every request with an API key, passed in the X-API-Key header. Keys start with sk-. The SDKs pick the key up from the BKBNLAB_API_KEY environment variable, or take it explicitly in the client constructor.

API keys

Keys are issued per workspace and carry a label, so several keys (staging, production, CI) can coexist and be told apart. Request a key if you don't have one yet. Treat it like a password: it grants full access to your workspace. 

curl https://api.bkbn.ai/v1/orders \
  -H "X-API-Key: $BKBNLAB_API_KEY"

Key rotation

Any key can rotate itself. The call returns the new secret once; the old secret stops working immediately, while the key keeps its label and its history. 

curl -X POST https://api.bkbn.ai/v1/api-keys/rotate \
  -H "X-API-Key: $BKBNLAB_API_KEY"

{ "data": { "uuid": "…", "name": "production", "key": "sk-…" } }

Rotate on a schedule, and immediately if a key may have leaked. Deploy the new secret before retiring the old call sites — there is no grace period.

Scopes

Keys have a scope: standard orders and reads its own work; admin additionally manages the key fleet (POST /v1/api-keys to issue, GET /v1/api-keys to list). Integrations should run on standard keys.

Failures

A missing or invalid key answers 401; a valid key calling an admin-scoped endpoint answers 403. Both use the standard error envelope — see Errors.

Header reference

HeaderValueRequired
X-API-KeyYour API key (sk-…).Yes — except GET /v1/features and asset downloads.
Content-Typeapplication/json on requests with a JSON body.For order, batch and asset-declaration calls.

Next steps