Authentication

Every APEX endpoint except GET /health and GET /openapi.yaml requires an API key in the X-API-Key header. This is the APEX-specific auth; shared conventions (errors, versioning) are in API conventions.

curl https://apex.tovr.eu/api/v1/analytics/overview \
  -H "X-API-Key: apex_3f2a9c41d88e0b7a5c6e1f9d2b4a8c0e1133557799aabbcc"

How keys work

• Keys look like apex_ followed by 48 hex characters, generated server-side from 24 bytes of cryptographic randomness.
• Only a SHA-256 hash of the key is stored. The raw key is returned exactly once at creation and cannot be recovered — losing it means issuing a new one.
• On every request the middleware hashes the presented key and looks it up among active keys. The key's last-used timestamp is updated asynchronously so validation never blocks on a write.
• A backend failure during validation denies access (403, never 5xx) — an unverifiable key is treated as invalid.

Getting a key

Keys are issued by TOVR operators. Each key carries a name (identifies the consumer in usage stats), an organization label (attached to request context for logging), and a per-minute request budget (see Rate limiting).

Revocation is a soft delete: the key is deactivated immediately and the record is kept for audit. There is no automatic rotation — issue a new key, switch your deployment, then revoke the old one.

Auth errors

The full catalog is in Errors.

Security practices

• Server-to-server only — never embed keys in client-side code or repositories.
• Store keys in a secret manager or environment variables.
• Use a separate key per environment/service so usage stats stay attributable.
• Watch last-used and per-key usage to find dead or runaway keys.
• Rotate after any suspected exposure (issue → switch → revoke).