Scopes

API key scopes control which operations a key can perform. Scopes are assigned when creating an API key and determine whether the key can read, write, or delete checks, and whether it can see or change alert channels.

Available Scopes

The alert scopes are separate from the check scopes: a checks:write key can’t add a webhook. Keys created before the alert scopes existed have neither.

Default Scope

API keys created without specifying scopes default to checks:read only. This means existing keys are read-only and cannot modify your checks.

Scope Requirements by Endpoint

Error Response

If your API key does not have the required scope, the API returns a 403 Forbidden:

{
  "error": "Credential does not have the required scope: checks:write"
}

Restricting a Key to Checks or Folders

Scopes control what a key may do. To also limit which checks it may do it to, restrict the key to specific checks and/or folders when you create it. A folder includes its subfolders. Checks outside the grant return 404, and a restricted key can only create checks inside an allowed folder. See Authentication for the full rules.

Creating a Scoped Key

When creating an API key in Settings > API, select the scopes you need. You can assign multiple scopes to a single key.

For full access to checks, enable checks:read, checks:write, and checks:delete. Add alerts:read and alerts:write to manage alert channels too.