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. The Developer page 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

Create the replacement.
Deploy it wherever the old one is used.
Confirm the new key's last-used time is moving on the Developer page.
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.