API-Tokens
Lege einen API-Token für PublicStatus an, wähle seine Scopes und sende ihn mit deinen Anfragen.
Stand:
Mit einem API-Token kann ein Skript oder ein anderer Dienst die API von PublicStatus in deinem Namen aufrufen. Seine Scopes bestimmen, welche Daten er lesen oder ändern darf.
Token anlegen
- Öffne Entwickler › API-Tokens.
- Wähle Neuen Token erstellen.
- Gib einen Namen ein, wähle die Scopes und das Ablaufdatum und bestätige mit deinem Passwort.
- Kopiere den Token. Er beginnt mit
kpat_und wird nur einmal angezeigt.
Ein Token läuft nach 90 Tagen ab, wenn du keinen anderen Ablauf wählst. Möglich sind höchstens 3650 Tage.
Token verwenden
Sende den Token im Header Authorization. Anfragen mit Token brauchen weder Cookie noch 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
Jeder Scope hat zwei Stufen. read erlaubt die lesenden Handler. write erlaubt alles, was read erlaubt, und zusätzlich die schreibenden Handler.
| Scope | Berechtigung | Handler |
|---|---|---|
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 |
Ratenbegrenzung
Jeder Token darf 120 Anfragen pro 60 Sekunden senden. Darüber antwortet die API mit 429 pat_rate_limited.
API-Tokens gibt es ab dem Team-Tarif.
Fehler
| HTTP-Status | Code | Ursache |
|---|---|---|
| 401 | missing_token |
Es fehlt der Header Authorization. |
| 401 | invalid_token |
Der Token ist unbekannt, widerrufen oder abgelaufen. |
| 403 | access_denied |
Dem Token fehlt der Scope für diesen Handler. |
| 403 | access_denied |
Der Endpunkt nimmt keine Tokens an. Tokens funktionieren nur an den API-Endpunkten. |
| 429 | pat_rate_limited |
Zu viele Anfragen mit diesem Token. |
| 403 | feature_disabled |
API-Tokens sind nicht Teil deines Tarifs. |
Token widerrufen
Widerrufe einen Token in Entwickler › API-Tokens, sobald du ihn nicht mehr brauchst. Wenn du dein Passwort änderst, werden alle deine Tokens widerrufen. Ein Token handelt immer mit deinen aktuellen Rollen. Verlässt du das Konto oder wird dein Benutzer gelöscht, funktioniert er nicht mehr.
Sicherheit
- Behandle einen Token wie ein Passwort. Bewahre ihn in einem Secret Store auf, nie im Code, in einem Repository, in einer App oder Webseite oder in einem Log.
- Gib jedem Skript einen eigenen Token mit nur den Scopes, die es braucht.
- Widerrufe Tokens, die du nicht mehr nutzt. Widerrufe einen Token sofort, wenn er in fremde Hände gelangt sein könnte.