Skip to content
StatusOwlDocs

Scopes

The scope catalog, which scope the two live endpoints require, and which scopes are reserved for endpoints that do not exist yet.

Last updated

Every API key carries a fixed set of scopes. A request is allowed only when the key holds the scope the endpoint requires. Scopes are chosen at key creation and can be edited later.

Most of this catalog grants access to nothing

Only two endpoints exist, and both require monitors:read. Every other scope in the table below is reserved vocabulary for endpoints that have not been built. Granting monitors:write or incidents:write to a key does not enable anything — there is no endpoint to call.

The catalog is documented so the strings themselves are on record. It is not a description of available functionality, and it is not what the key creation dialog offers — see Scope catalog below.

What is enforced today

EndpointRequired scope
GET /v1/monitorsmonitors:read
GET /v1/monitors/{monitor_uuid}monitors:read

That is the complete list. monitors:read can be granted on every plan, so the API is usable on every plan including Free.

Scope catalog

ScopeStatusWould grant
account:readReservedOrganization name, plan and basic settings
monitors:readLiveList and fetch monitor configuration
monitors:writeReservedCreate, update and delete monitors
incidents:readReservedList incidents and their history
incidents:writeReservedOpen, update and resolve incidents
status-pages:readReservedStatus page configuration and component state
status-pages:writeReservedUpdate page configuration and branding
metrics:readReservedTime-series check results and uptime percentages
audit-logs:readReservedOrganization audit log entries

"Reserved" means the string is valid vocabulary and no endpoint consumes it. On the current plans only account:read and monitors:read can actually be granted — the key creation dialog shows those two. The rest of the catalog is listed here so the strings are documented, not because they can be selected. Write endpoints are on the roadmap.

Scopes are exact, and there is no hierarchy

Scope strings are compared exactly. There is no wildcard: monitors:* is not a scope. monitors:write does not imply monitors:read — a key that needs both must be granted both.

The 403 shape

When a key is missing a required scope:

json
{
  "error": "Missing required scope",
  "required_scope": "monitors:read",
  "granted_scopes": ["account:read"]
}

For endpoints that accept any one of several scopes:

json
{
  "error": "Missing required scope",
  "required_scopes_any_of": ["monitors:read", "monitors:write"],
  "granted_scopes": ["account:read"]
}

granted_scopes is there so you can confirm what the key holds from a log line, without dashboard access.

Editing scopes

From the ⋯ menu next to a key → Edit. Changes apply on the next request; there is no cache to wait out. Editing does not change the key's plaintext — use Rotate for that.

See also