Authentication

Every /v1/saas/* endpoint except POST /auth/register and POST /auth/login requires a bearer API key:

curl https://api.lecturia.ai/v1/saas/me \
  -H "Authorization: Bearer lk_live_..."

Key kinds

Both kinds use the same base URL — the key alone selects the environment. There is no separate sandbox hostname.

What is NOT accepted

• Session JWTs. The tokens returned by /auth/register and /auth/login are account sessions, not API credentials. Presenting one on any other /v1/saas/* route returns 403 bearer_not_allowed_on_saas.
• Query-string keys. The key travels in the Authorization header, never in the URL.

Scopes

Keys carry scopes: read, write, admin. Administrative endpoints (key minting, webhook management) require admin; a key can only mint keys with a subset of its own scopes (403 scope_escalation otherwise). Give day-to-day integrations read+write and keep an admin key aside.

Key lifecycle

• Plaintext is returned exactly once at mint (and on webhook secret rotation, once again). Only a hash is stored server-side — a lost key is a revoke-and-remint, never a recovery.
• Revoke with DELETE /v1/saas/keys/{id}. Revocation propagates in seconds; the revoked key answers 401 api_key_revoked.
• last_used_at in GET /keys may lag ~60 s (coalesced writes).

Rate limits and errors

Auth endpoints are velocity-limited (429 rate_limited — back off and retry). Every error is the uniform envelope described in Error codes.