Ereignisse auflisten

GET /v1/events · Berechtigung events:read

Gibt die Ereignisse der Umgebung in chronologischer Reihenfolge zurück, das älteste zuerst. Jedes Ereignis ist dasselbe Dokument mit derselben id, das Webhooks ausliefern. Ereignisse werden bei jedem Tarif 30 Tage aufbewahrt.

Verwenden Sie diesen Endpoint, wenn Ihr System keine Webhooks empfangen kann oder um eine Lücke nach einem Ausfall zu schließen: Speichern Sie den zuletzt verarbeiteten next_cursor und setzen Sie von dort aus fort.

Die Umgebung ergibt sich immer aus dem API-Schlüssel; es gibt keinen Parameter für die Umgebung.

Anfrage

Parameter In Pflicht Beschreibung
after query nein next_cursor aus der vorherigen Antwort oder latest, um nur ab jetzt aufgezeichnete Ereignisse zu erhalten. Ohne diesen Parameter beginnt die Liste mit dem ältesten gespeicherten Ereignis.
types query nein Durch Kommas getrennte Ereignistypen, höchstens 20, z. B. user.created,user.deleted. Ohne diesen Parameter werden alle Typen zurückgegeben.
org_id query nein Nur Ereignisse dieser Organisation (org_…).
limit query nein Seitengröße, 1 bis 100. Standard: 20.
payload query nein thin (Standard) oder full. full erfordert zusätzlich die Berechtigung users:read. Solange die vollständige Nutzlast nicht verfügbar ist, gibt full die reduzierte Nutzlast zurück.
purpose query nein tail (Standard) oder webhooks_listen. webhooks_listen wird nur in den Umgebungen development und staging akzeptiert.

Antwort

200 OK:

Feld Beschreibung
data Ereignisse in chronologischer Reihenfolge. Jedes Ereignis hat eine seq, die innerhalb der Umgebung steigt.
next_cursor Immer vorhanden. Übergeben Sie ihn als after in der nächsten Anfrage, auch wenn data leer ist.
has_more true, wenn weitere Ereignisse folgen; fragen Sie sofort erneut ab. Bei false warten Sie vor der nächsten Abfrage (5 bis 60 Sekunden).

Der Cursor hängt nicht von types oder org_id ab: Sie können den Filter ändern und von derselben Position aus fortfahren. Ein Cursor funktioniert nur in der Umgebung, die ihn ausgegeben hat.

{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "type": "connection.deleted",
      "schema_version": 1,
      "environment_id": "env_01j9xk3m7q8r2s4t6v8w0y2z4e",
      "occurred_at": "2026-11-03T08:15:42.120Z",
      "recorded_at": "2026-11-03T08:15:42.140Z",
      "seq": 4182,
      "data": {
        "object": {"id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4f", "status": "deleted"},
        "object_version": 2
      },
      "context": {"actor": {"type": "system"}, "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182"}
    }
  ],
  "next_cursor": "eyJ2IjoxfQ.c2lnbmF0dXJl",
  "has_more": false
}

Beispiel: Auf neue Ereignisse abfragen

cursor=latest
while true; do
  page=$(curl -sS -G https://api.keenauth.com/v1/events \
    -H "Authorization: Bearer $KEENAUTH_API_KEY" \
    --data-urlencode "after=$cursor" --data-urlencode "limit=100")
  echo "$page" | jq -c '.data[]'
  cursor=$(echo "$page" | jq -r '.next_cursor')
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || sleep 10
done

Die CLI macht dasselbe mit keenauth events tail.

Fehler

Jeder Fehler ist ein application/problem+json-Body mit einem stabilen code.

HTTP code Wann
400 invalid_cursor Der Cursor ist fehlerhaft oder wurde in einer anderen Umgebung ausgegeben.
401 unauthenticated Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
403 insufficient_permissions Dem Schlüssel fehlt events:read oder payload=full ohne users:read.
403 test_feature_not_in_production purpose=webhooks_listen in einer Produktionsumgebung.
422 validation_failed Ein Parameter ist ungültig oder mehrfach angegeben; errors[].pointer nennt ihn.
429 rate_limited Das Ratenlimit wurde überschritten; beachten Sie Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut.

Personenbezogene Daten

Dieser Endpoint enthält personenbezogene Daten: Ereignisse. Personenbezogene Daten in den KeenAuth-APIs beschreibt, welche Daten gespeichert werden, wie lange sie aufbewahrt werden und wie sie gelöscht werden. Senden Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).