API keys

A key carries one of two scopes, chosen when you create it and fixed for its lifetime:

• Read — list and inspect monitors, incidents, heartbeats and status pages.
• Write — everything read allows, plus creating, changing, pausing and deleting.

There is no way to widen an existing key: a read key that needs to write is replaced by a new write key, not upgraded. Calling a write route with a read key returns 403, never a partial success.

Scopes are deliberately coarse. A key reaches only the routes Fettle marks as public API — billing, organization management and user management are never reachable with a key, whatever its scope.

The secret is shown once, when the key is created, and never again. Fettle stores only a hash; nobody at Fettle can read your key back to you, and neither can the dashboard.

What the dashboard does show is the prefix — the first characters of the secret — so you can tell which key a log line or an alert refers to without holding the secret itself.

Rotating a key issues a new secret while the old one keeps working for a 24-hour grace period. That window is the point: it lets you deploy the new secret everywhere it is used before the old one stops, so rotation is not an outage.

When a key is compromised, do not rotate — revoke. Revocation takes effect immediately, with no grace window, and cannot be undone.

A key can be given an expiry date, after which it stops working on its own. Useful for a contractor, a demo, or a one-off migration script — the cleanup happens whether or not anyone remembers it.

A key can also be pinned to one or more CIDR ranges. Requests from anywhere else are rejected before the key is even considered valid. This is worth setting for a key that only ever calls from a known CI runner or a fixed egress address.

Two limits apply per organization: how many keys may exist at once, and how many requests per minute all of them together may make.

The rate limit is shared across every key in the organization, not budgeted per key — a second key does not buy a second allowance. Exceeding it returns 429 with a retry_after value telling you how many seconds to wait.

MCP tool calls spend the same budget: one tool call is one request, whichever channel it arrives on. See MCP.

Keys are created, rotated and revoked in Settings → API Keys. Each key records when it was last used, so a key nothing calls any more is easy to find and remove.