Authentication

Header format

Set the Authorization header on every request:

Authorization: Bearer lvk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens match lvk_(live|test)_ followed by at least 20 base64url characters. A freshly minted token is 43 characters of random base64url after the prefix.

Key modes

• lvk_live_… — production key. Calls hit real providers and draw against your credit balance.
• lvk_test_… — test key. Same runtime behavior as a live key (there is no mocked-response sandbox); the prefix is purely a label you can filter on in the dashboard and audit log. Calls made with a test key are still billed.

Minting keys

Create and manage keys from Dashboard → API Keys. The plaintext token is returned once at creation time — store it in a password manager or secrets manager immediately. We never display it again.

The REST equivalent is POST /v1/keys (session-authenticated via your dashboard login, not API-key-authenticated) — see the /v1/keys reference.

Errors

Unauthenticated requests return a JSON body with an error.code of unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or malformed Authorization header. Expected: Bearer lvk_live_…"
  },
  "request_id": "2e6b…"
}

Also returned with HTTP 401 when the token does not match the lvk_(live|test)_… shape, the key is unknown, or the key has been revoked.

Rotating keys

Best practice: keep at least two active keys and rotate on a schedule. To rotate without downtime:

1. Mint a new key in the dashboard.
2. Roll the new key out to your servers (env var swap).
3. Confirm traffic is hitting the new key via the last_used_at field on GET /v1/keys.
4. Revoke the old key.

If a key leaks

Revoke immediately from Dashboard → API Keys → Revoke or via DELETE /v1/keys/:id. Revocation busts the auth cache within seconds; further requests with the revoked token return 401 unauthorized. Tokens are stored as SHA-256 hashes server-side — we cannot recover a lost key, only revoke and re-issue.

Storage & hashing

Each key carries 256 bits of entropy from crypto.getRandomValues(). On creation we store only (a) the 12-character prefix for O(1) lookup and (b) the SHA-256 hash of the full token. At request time the Worker re-hashes the presented bearer token and compares it in constant time.