Authentication

Bearer tokens#

Every request to /v1/* carries one header:

Authorization: Bearer <token>

The token is an API key. Every key of an account shares the account's burst limit and monthly quota.

API keys#

An API key is a prefix followed by a random body: lgv_ plus 64 characters in production. You create keys on /account, each with a name, up to 10 per account. The server stores only a hash; the account page keeps the prefix and the first 8 characters of the body so you can tell keys apart.

curl https://api.legivel.com/v1/usage \
  -H "Authorization: Bearer $LEGIVEL_API_KEY"

See Get your API key for the steps.

Failures#

A missing, malformed, expired or revoked token gets a 401 with a stable code and a WWW-Authenticate: Bearer header:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{"code":"unauthorized","error":"missing or invalid bearer token"}

A burst of unknown keys from one IP is throttled to keep the database out of the loop. Throttled requests still answer 401, so a misconfigured client sees 401 for a bad key, never 429.

Revocation#

Revoke a key on the account page (Revoke, then Confirm revoke). Verified keys are cached in the server for 60 seconds, and a database trigger evicts the cached entry the moment a key is deleted. In normal operation revocation is effective immediately; if that channel is down, the worst case is 60 seconds.

Security notes#

• Send keys only over HTTPS. The API is served over HTTPS; plain HTTP is redirected.
• Keep keys in environment variables or a secret store, not in source control.
• Use one key per deployment so revoking one does not break the others.
• Per-key usage on GET /v1/usage shows which key did what.