Authentication

Every request carries a bearer key. Keys are scoped to one workspace and can be rotated without downtime.

Sending the key

Authorization: Bearer lm_live_7a3f...c9d2

Keys prefixed lm_test_ work against the sandbox and never touch production data or billing. The sandbox shares the same schema, so a client that passes there passes in production.

Rotation

Create the replacement key first, deploy it, then revoke the old one. Revocation is immediate — in-flight requests keep their already-authenticated state, new ones get 401:

POST /v1/keys
{"label":"ci-runner","scopes":["extract","summarize"]}
Keys are shown once, at creation. Store them in your secret manager, not in a repository or a client build.

Scopes

ScopeGrants
extract/v1/extract, /v1/ocr
translate/v1/translate
summarize/v1/summarize
read/v1/jobs, /v1/usage

Webhooks

Asynchronous jobs notify a URL you register per workspace. Payloads are signed with X-Lumen-Signature (HMAC-SHA256 over the raw body and a timestamp header); reject anything older than five minutes to block replays. Retries back off at 1, 5 and 30 minutes.

{
  "event": "job.done",
  "job": { "id": "jb_77d0e4", "status": "done", "pages": 42 }
}