Authentication & keys

Every call to the Partner API carries an HTTP bearer token.

Authorization: Bearer lk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

API keys

• A key is lk_live_ / lk_test_ + 32 random alphanumerics (~190 bits of entropy).
• The full key is shown once, at creation. Store it in your secret manager — Lockey keeps only a hash and the 12-char prefix (for display).
• Keys are environment-bound: the prefix (lk_test_ vs lk_live_) selects sandbox or live behavior against the same base URL.

Uniform auth failures (no probing)

Any auth problem — missing header, unknown key, revoked, expired, or a suspended org — returns the same opaque response:

401 { "error": "unauthorized" }

This is deliberate: the response does not tell an attacker which of those conditions failed, so the endpoint can't be used to probe for valid keys or org state.

Scopes

Keys are minted with a subset of capabilities. A call missing the required scope returns:

403 { "error": "insufficient_scope", "scope": "<scope>" }

Scope	Grants access to
requests:write	Create document requests
requests:read	List / fetch requests
grants:read	List / fetch grants and mint viewing sessions
webhooks:write	Reserved — not yet implemented (poll instead)
verify:read	Reserved — not yet implemented

Grant each key the least set of scopes its job needs. A backend that only creates requests and reads results needs requests:write + requests:read; add grants:read only where you actually render documents.

Rotating keys

Because the plaintext key is never recoverable after creation, rotation is: mint a new key → deploy it → revoke the old one from the console. Keep the two overlapping briefly so in-flight calls don't fail.

Next: Requesting documents →