API-Authentifizierung

Diese Seite behandelt die öffentliche REST-API (/api/v1/*) — jene, die Ihre eigenen Skripte, CI-Pipelines oder Integrationen aufrufen. Sie ist getrennt vom Browser-Login, mit dem Sie sich am Dashboard anmelden (der läuft im Hintergrund über Keycloak/OIDC und geht API-Clients nichts an).

Voraussetzungen

Die öffentliche API ist dem Tarif Max vorbehalten.

API-Schlüssel erzeugen

1. Gehen Sie zu Einstellungen → API-Schlüssel.
2. Geben Sie dem Schlüssel einen Namen und optional ein Ablaufdatum (leer lassen für einen Schlüssel ohne Ablauf).
3. Klicken Sie auf Neuen Schlüssel erzeugen.
4. Kopieren Sie den Schlüssel sofort — er wird nur einmal angezeigt (oks_live_...).

Schlüssel lassen sich auf derselben Seite rotieren (neuer Wert, gleicher Eintrag) oder widerrufen; bei einem ablaufenden Schlüssel erhält der Owner der Organisation 30, 14 und 7 Tage vorher eine E-Mail. Siehe Kontosicherheit.

Eine Anfrage authentifizieren

Senden Sie den Schlüssel bei jeder Anfrage als Bearer-Token:

GET /api/v1/monitors HTTP/1.1
Host: api.okstatus.eu
Authorization: Bearer oks_live_xxxxxxxxxxxxxxxx

curl https://api.okstatus.eu/api/v1/monitors \
  -H "Authorization: Bearer oks_live_xxxxxxxxxxxxxxxx"

Ein fehlender oder fehlerhafter Schlüssel liefert 401 UNAUTHORIZED. Ein gültiger Schlüssel, dessen Organisation nicht im Max-Tarif ist, liefert 403 FORBIDDEN.

Ratenbegrenzung

Anfragen sind je Organisation gedeckelt: 1000 Anfragen/Stunde. Jede Antwort enthält:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1700000000

Wird das Limit überschritten, kommt 429 RATE_LIMITED.

Fehlerformat

Jede Fehlerantwort — über alle Endpunkte hinweg — hat dieselbe Form:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor not found"
  }
}

Was die API abdeckt

Ressource	Endpunkte
Monitors	/monitors, /monitors/{id}, /monitors/{id}/checks, /monitors/{id}/uptime
Vorfälle	/incidents, /incidents/{id}, /incidents/{id}/resolve
Wartungen	/maintenances, /maintenances/{id}
Statusseiten	/status-pages, /status-pages/{id}
Alarmkanäle	/alert-channels, /alert-channels/{id}
Status-Momentaufnahmen	/status, /status/summary
Organisation	/org

Alle liegen unter https://api.okstatus.eu/api/v1. Die Schemata für Anfragen und Antworten stehen für jeden Endpunkt in der interaktiven Referenz.

Interaktive Referenz

Die vollständige, stets aktuelle Endpunktliste (Anfrage-/Antwortschemata, „Try it out”) finden Sie in der interaktiven OpenAPI-Referenz. Die Spezifikation selbst (/api/v1/openapi.json) ist ohne Schlüssel erreichbar und lässt sich damit in Codegen-Werkzeuge einspeisen.