Docs menu

First stepsAuthentication

Authentication

Every request carries a Bearer token: an API key from the account page.

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. Two paths need no key: the health probe and the OpenAPI document at GET /v1/openapi.json, which is public so a client can read the API before it has a key.

API keys#

An API key is a prefix followed by a random body: lgvl_ 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 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": "The API key is missing or not valid. Send it as \"Authorization: Bearer <key>\"."
}

A burst of unknown keys from one client address is limited to keep the database out of the loop: the address may have 10 keys checked that the server has not seen valid in the last 24 hours, refilled at one a second. Over that, the answer is 429 rate_limited with a Retry-After header, and limit names key_verifications; the key is not checked, so a valid key sent in such a burst is refused the same way. A key that was valid in the last 24 hours never counts against the budget, so an office or a CI farm can send many keys from one address. See Errors and quota.

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.