Authorization header. Pick the credential that fits the caller.
How to send it - it works as a Bearer token, and is also accepted via
X-API-Key. A Bearer token always takes precedence over a browser session cookie.
Permissions
Access is governed by role-based permissions on each resource. A403 response names the permission the call needs, so you can grant least privilege.
The built-in roles - Admin, Manager, and Viewer - cover common cases; create custom roles for tighter scoping. Grant a service token the minimum it needs.
Security
- A raw token is shown exactly once - store it in a secret manager at creation.
- Use one credential per consumer; set an expiry and rotate before it lapses.
- Never log the secret (log the token ID instead) and never commit it.