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
| Scope | Grants |
|---|---|
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 }
}