API scopes & plan gating
The full scope catalog and which scopes are available on each StatusOwl plan.
Every API key carries a fixed set of scopes — granular permissions that
tell the API what the key can do. A key with monitors:read can list and
fetch monitors; the same key calling a write endpoint gets a 403. Scopes are
chosen at key creation time and can be edited later (within the limits of
your plan).
This page lists every scope StatusOwl supports and shows which scopes each plan tier can grant.
Scope catalog
| Scope | Tier | Grants |
|---|---|---|
account:read | account | Read organization name, plan, and basic account settings |
monitors:read | monitoring | List and fetch monitor configuration. Does not include time-series check data |
monitors:write | monitoring | Create, update, and delete monitors. Toggle maintenance mode |
incidents:read | monitoring | List incidents and their history |
incidents:write | monitoring | Create, update, resolve, and post updates to incidents |
status-pages:read | advanced | List status page configuration and component state |
status-pages:write | advanced | Update status page configuration, components, and branding |
metrics:read | advanced | Time-series check results, response times, uptime percentages |
audit-logs:read | advanced | Access organization audit log entries |
The tier column maps each scope to the section it appears under in the dashboard's key creation dialog (Account / Monitoring / Advanced) — purely a UI grouping; it does not affect runtime semantics.
Plan → allowed scopes
The set of scopes you can grant on a new key is gated by your organization's current plan:
| Plan | Allowed scopes |
|---|---|
| Free | account:read, monitors:read |
| Team | Free + incidents:read, status-pages:read, audit-logs:read |
| Pro / Business | Team + monitors:write, incidents:write, status-pages:write, metrics:read |
| Enterprise | All scopes |
The dashboard hides disallowed scopes from the create / edit picker automatically — there's no way to accidentally select a scope your plan doesn't grant.
Read vs write
monitors:read lets you list and fetch monitor configuration but does
not include time-series check data (response time samples, uptime
percentages, per-region history). That data lives behind metrics:read,
which is a separate scope on a separate plan tier.
monitors:write does not imply monitors:read — if a key needs both,
grant both. There's no implicit hierarchy.
Endpoint → required scope
Each documented endpoint specifies which scope it requires. The current mapping for shipped endpoints:
| Endpoint | Required scope |
|---|---|
GET /v1/monitors | monitors:read |
GET /v1/monitors/{monitor_uuid} | monitors:read |
Endpoints for the other scopes (monitors:write, incidents:*, metrics:read,
etc.) are reserved in the catalog but not yet shipped. See the
Monitors API doc for the current surface and
what's planned.
403 response shape
When a key is missing the scope an endpoint requires, the API returns
403 Forbidden with a structured body that names the missing scope and
echoes the scopes the key actually has:
{
"error": "Missing required scope",
"required_scope": "monitors:write",
"granted_scopes": ["monitors:read"]
}
Some endpoints accept any one of several scopes (for example, a read path that's also fine with the corresponding write scope). Those return the alternative shape:
{
"error": "Missing required scope",
"required_scopes_any_of": ["monitors:read", "monitors:write"],
"granted_scopes": ["account:read"]
}
In both cases the granted_scopes field is a debugging aid — confirm the
key has what you think it has, then either add the missing scope (if your
plan allows it) or rotate to a higher-scope key.
Editing scopes on an existing key
Scopes can be edited any time from the ⋯ menu next to a key → Edit. The change takes effect on the next request. Scopes that have since become disallowed by your plan are hidden from the picker and will be dropped silently if they're still on the key.
Edits do not change the key's plaintext — only its permissions. If you need a new secret, use Rotate instead.
Downgrade behavior
If you downgrade a plan and an existing key has scopes that the new plan doesn't grant, requests using the disallowed scope start returning 403. The key itself keeps working for any scopes that are still allowed — only the disallowed scopes are blocked.
To clean up: edit the affected keys, deselect the now-disallowed scopes (or drop the key entirely if it's no longer useful), and save. The dashboard also shows a banner when a downgrade has left keys with disallowed scopes.