Skip to main content
SitePulse v1 uses Laravel Passport OAuth2 personal access tokens. Each token belongs to the SitePulse user who created it and acts on that user’s behalf.

​
Personal access tokens

Create and revoke tokens in the dashboard under Settings → API tokens. For AI clients, use Settings -> MCP instead. MCP supports browser OAuth for compatible clients and a scoped token fallback for clients that need bearer-token auth. See MCP integrations.

​
Request headers

Send the token on every request: 
Authorization: Bearer {access_token}
Accept: application/json
For POST, PATCH, and PUT requests with a body, also send: 
Content-Type: application/json

​
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

ScopeDescription
teams:readRead teams, plan limits, and team monitoring defaults
teams:writeUpdate team monitoring defaults (cadence, thresholds, escalation)
sites:readRead sites and site monitoring data
sites:writeCreate and update sites
sites:deleteDelete sites
checks:readRead check runs and results
checks:runQueue manual check runs
checks:deleteDelete manual check runs
issues:readRead issues (monitoring incidents)
Scopes map to team permissions. For example, sites:write satisfies the createSite and updateSite permissions when the token is used. 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: 
teams:read
sites:read
checks:read
issues:read
Perfect for dashboards and monitoring displays.
Add teams:write to read team monitoring settings:
teams:read
teams:write
Add sites:write to the read-only set:
teams:read
sites:read
sites:write
checks:read
issues:read
Add checks:run for running checks:
teams:read
sites:read
checks:read
checks:run
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:
{
  "message": "An active team subscription is required."
}
3

Role permissions

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

​
What v1 does not support

The public v1 API documented here is limited to personal access tokens created in the dashboard. MCP has its own remote server and install flow. The following are not part of the v1 API guide:
  • Third-party OAuth authorization code flows for the JSON API
  • Client credentials / machine-only tokens for customers
  • Anonymous or unauthenticated endpoints

​
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