Keys, scopes and rotation

How authentication works

Send the key in Authorization: Bearer <key> or X-API-Key: <key>. That is the only way to authenticate. A browser session does not authenticate an API call, on purpose: an API that accepted a cookie could be driven by any web page your browser happens to load.

Every rejection looks the same

An unknown key, a revoked key, an expired key and a key belonging to a disabled user all return the same 401:

{"error": {"code": "unauthorized", "message": "Invalid or expired API key."}}

If they read differently, anyone holding a stolen list of key ids could work out which were still live.

Scope is derived from the method

A read-only key may use GET, HEAD and OPTIONS. Anything else is a 403 with code forbidden. The check is on the HTTP method rather than a per-endpoint flag, so a read-only key can list a collection whose POST it may not call, and no new mutating endpoint can forget to protect itself.

Practice worth following

• One key per system. Monitoring, CI, and your laptop get separate keys, so revoking one does not break the other two.
• Read-only unless it needs to write. A dashboard that lists servers has no business being able to destroy them.
• Set an expiry on anything temporary. A key for a one-week migration should not still work next year.
• Name keys after where they live, so deploy-ci and grafana-prod rather than key1 and key2. Settings → API keys shows the name, the last-used time and the last-used address, which is what makes an unused key obvious.
• Never commit a key. Environment variables or your platform's secret store. Anything in a repository is public the moment the repository is.

Rotating

1. Create the replacement.
2. Deploy it wherever the old one is used.
3. Confirm the new key's last-used time is moving under Settings → API keys.
4. Revoke the old one.

Revoking takes effect immediately. Keys are revoked rather than deleted, so the audit history of what that key did stays readable.

If a key leaks

Revoke it first, then work out what it touched. A full-scope key could have deployed or destroyed servers, so check your server list and your credit balance next, and open a ticket if either holds something you did not do.