Skip to main content

​
Personal access tokens

Create and revoke tokens in the dashboard under Settings → API tokens.

​
Request headers

Send the token on every request:
For POST, PATCH, and PUT requests with a body, also send:

​
Token lifetime

Personal access tokens expire six months after they are created. Expired or revoked tokens return 401 Unauthorized.

​
Email verification

All /api/v1/* routes require a verified email address on the token owner. Unverified users receive an authentication error.

​
OAuth scopes

Each token carries one or more scopes. Routes declare the minimum scope required. If the token lacks that scope, the API returns 403 Forbidden even when the user would otherwise be allowed in the UI.

​
Available scopes

Scopes map to team permissions and team role rules still apply: a member without site-create permission cannot create sites even with sites:write on the token.
Different use cases require different scope combinations:
Perfect for dashboards and monitoring displays.
Add teams:write to update team monitoring defaults (cadence, thresholds, escalation):
Add sites:write to the read-only set:
Add checks:run for running checks:
Grant only the scopes you need. This follows the principle of least privilege.

​
Team access and billing

Authentication proves who is calling. Team routes also enforce:
1

Membership

The user must belong to the team in the URL (or implied by the site/check/issue).
Otherwise the API returns 404 to avoid leaking cross-tenant resources.
2

Active subscription

The team must have active plan access.Otherwise the API returns 402 with:
3

Role permissions

Site, check, and issue policies apply on top of token scopes.

​
Security practices

Store securely

Store tokens in secrets managers, not source control

Separate environments

Use separate tokens per environment (staging vs production)

Revoke immediately

Revoke tokens immediately when an integration is retired

Narrow scopes

Prefer narrow scopes and dedicated service users where your plan allows

​
Creating a token

Tokens are created under Settings → API tokens in the dashboard. Give each token a descriptive name (for example “CI Pipeline”) and select the required scopes.
The token value is shown once at creation. Store it securely - it cannot be retrieved again.

​
See also