API Keys

Creating a key

Settings → API Keys → Generate new key. Three things to fill in: a name (something a teammate could grep for — "Grafana", "Watchdog cron"), the scopes you need (read:* / write:* / admin:* per resource — pick narrowest), and an optional expiry. Best practice is to rotate every 90 days even if you don't have to; it forces you to actually look at what's using the key.

The raw key (mpk_*) appears once. We store only the bcrypt hash. If you lose the key, you don't recover it — you revoke and generate a new one. This is the right behavior even though it's mildly annoying; the alternative is us holding a recoverable secret, which is worse.

Scopes

The full scope reference lives on the API authentication page. Pick the narrowest set that works. A read-only Grafana key shouldn't have write or admin; a watchdog only needs read:servers. Narrow scopes are easier to audit, easier to rotate, easier to revoke without thinking.

Audit usage

Each key shows last-used timestamp, last-used IP, and request count over the last 30 days. Keys unused for 60+ days get flagged for review on the API Keys list. The flag is informational — we don't auto-revoke.

Rotation

The standard four-step dance: generate a new key with the same scopes, update the consumer to use it, confirm the old key's last-used timestamp stops advancing (which means the consumer fully migrated), then revoke the old one. Skipping step 3 is how you silently break things — the consumer might have multiple instances and one of them is still on the old key.

Revoking everything

If you suspect a key leaked or someone left the team with access, "Revoke all keys" rolls the org's signing salt. Every existing key 401s within 60 seconds. After that you regenerate from scratch. It's nuclear but quick.