# Authentication

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

Page: https://legivel.com/docs/authentication

## Bearer tokens

Every request to `/v1/*` carries one header:

```text
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](https://legivel.com/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.

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

See [Get your API key](https://legivel.com/docs/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:

```json
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](https://legivel.com/docs/api/usage) shows which key did what.

Keys are shown once

The full key is displayed only at creation. A lost key cannot be recovered: create a new one and revoke the old.