API

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

  1. Öffne Entwickler › API-Tokens.
  2. Wähle Neuen Token erstellen.
  3. Gib einen Namen ein, wähle die Scopes und das Ablaufdatum und bestätige mit deinem Passwort.
  4. 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.