API tokens
Create an API token for PublicStatus, choose its scopes and send it with your requests.
Last updated:
An API token lets a script or another service call the PublicStatus API in your name. Its scopes decide which data it may read or change.
Create a token
- Open Developer › API tokens.
- Choose Create a new token.
- Enter a name, pick the scopes and the expiry, and confirm with your password.
- Copy the token. It starts with
kpat_and is shown only once.
A token expires after 90 days unless you pick another expiry. The longest possible expiry is 3650 days.
Use the token
Send the token in the Authorization header. Requests with a token need no cookie and no CSRF token.
curl -X POST https://status.example.com/api/query \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "publicstatus:query:component:detail",
"payload": {
"id": "00000000-0000-4000-8000-000000000001"
}
}'
Scopes
Each scope comes in two levels. read allows the read handlers. write allows everything read allows plus the write handlers.
| Scope | Grant | Handlers |
|---|---|---|
components (Components) |
components:read |
publicstatus:query:component:detail, publicstatus:query:component:list |
components (Components) |
components:write |
publicstatus:write:component:create, publicstatus:write:component:delete, publicstatus:write:component:update |
incidents (Incidents) |
incidents:read |
publicstatus:query:incident:detail, publicstatus:query:incident:list, publicstatus:query:incident:updates |
incidents (Incidents) |
incidents:write |
publicstatus:write:incident:open, publicstatus:write:incident:post-update, publicstatus:write:incident:resolve, publicstatus:write:incident:update |
maintenance (Maintenance) |
maintenance:read |
publicstatus:query:maintenance:detail, publicstatus:query:maintenance:list |
maintenance (Maintenance) |
maintenance:write |
publicstatus:write:maintenance:cancel, publicstatus:write:maintenance:complete, publicstatus:write:maintenance:schedule, publicstatus:write:maintenance:start |
monitors (Monitors) |
monitors:read |
publicstatus:query:monitor:detail, publicstatus:query:monitor:list, publicstatus:query:monitor:uptime-public |
monitors (Monitors) |
monitors:write |
publicstatus:write:monitor:check-now, publicstatus:write:monitor:create, publicstatus:write:monitor:delete, publicstatus:write:monitor:mint-heartbeat-token, publicstatus:write:monitor:update |
webhooks (Webhooks) |
webhooks:read |
publicstatus:query:webhook-subscriber:detail, publicstatus:query:webhook-subscriber:list |
webhooks (Webhooks) |
webhooks:write |
publicstatus:write:webhook-subscriber:create, publicstatus:write:webhook-subscriber:delete, publicstatus:write:webhook-subscriber:reactivate, publicstatus:write:webhook-subscriber:rotate-secret, publicstatus:write:webhook-subscriber:update |
Rate limit
Each token may send 120 requests per 60 seconds. Above that the API answers 429 pat_rate_limited.
API tokens are available from the Team plan.
Errors
| HTTP status | Code | Cause |
|---|---|---|
| 401 | missing_token |
No Authorization header. |
| 401 | invalid_token |
The token is unknown, revoked or expired. |
| 403 | access_denied |
The token lacks the scope for this handler. |
| 403 | access_denied |
The endpoint does not accept tokens. Tokens work only on the API endpoints. |
| 429 | pat_rate_limited |
Too many requests from this token. |
| 403 | feature_disabled |
API tokens are not part of your plan. |
Revoke a token
Revoke a token in Developer › API tokens as soon as you stop using it. Changing your password revokes all your tokens. A token always acts with your current roles. If you leave the account or your user is deleted, it stops working.
Security
- Treat a token like a password. Keep it in a secret store, never in code, a repository, an app or web page, or a log.
- Give each script its own token with only the scopes it needs.
- Revoke tokens you no longer use. Revoke a token at once if it may have leaked.