Protokolle auflisten

GET /v1/logs · Berechtigung logs:read

Listet die Protokolleinträge der Umgebung auf (Anmeldungen, Sitzungen, Tokens, MFA, Angriffsschutz und mehr) mit Cursor-Paginierung, neueste zuerst. Einträge, die älter als der Aufbewahrungszeitraum Ihres Tarifs sind (Free 7, Startup 14, Business 30, Enterprise 90 Tage), werden nie zurückgegeben.

Anfrage

Parameter In Erforderlich Beschreibung
limit query nein Seitengröße, 1 bis 100. Standard 20.
after query nein Undurchsichtiger Cursor aus list_metadata.after (ältere Einträge). Schließt before aus.
before query nein Undurchsichtiger Cursor aus list_metadata.before (neuere Einträge). Schließt after aus.
from query nein RFC-3339-Zeitpunkt; Einträge ab diesem Zeitpunkt. Muss innerhalb des Aufbewahrungszeitraums liegen.
to query nein RFC-3339-Zeitpunkt; Einträge vor diesem Zeitpunkt. Muss nach from liegen.
type query nein Präfix des Protokolltyps wie authentication. oder session.created. Wiederholen Sie den Parameter für bis zu 20 Werte; ein Eintrag, der einem dieser Werte entspricht, wird zurückgegeben.
outcome query nein success, failure, denied oder error.
user_id, org_id, application_id, connection_id, directory_id, session_id query nein Genaue Übereinstimmung mit der ID inklusive Präfix (usr_, org_, app_, conn_, dir_, ses_).
request_id query nein Idp-Request-Id einer Anfrage (UUID), zum Beispiel die ID, die auf einer gehosteten Anmeldefehlerseite angezeigt wird.
correlation_id query nein Idp-Correlation-Id eines Workflows (UUID).
ip query nein IP-Adresse oder CIDR-Block (203.0.113.0/24). Erfordert audit-events:read_ip.
ip_country query nein Land der IP, ISO 3166-1 Alpha-2 in Großbuchstaben (DE).
q query nein Präfix des maskierten Identifikatorhinweises (j***@). Erfordert users:read_pii.

Einträge werden immer nach occurred_at sortiert, neueste zuerst; einen order-Parameter gibt es nicht (order=desc wird akzeptiert, jeder andere Wert schlägt mit validation_failed fehl). Ein Cursor ist nur mit den Filtern gültig, für die er ausgestellt wurde.

Die Filter ip und q benötigen ihre Berechtigung, auch wenn sie das Ergebnis nur eingrenzen: Ohne sie schlägt die Anfrage mit 403 insufficient_permissions fehl, bevor eine Suche stattfindet, sodass ein Schlüssel keine Werte abfragen kann, die er nicht lesen darf.

Antwort

200 OK. data enthält die Einträge der Seite; list_metadata.after verweist auf ältere und list_metadata.before auf neuere Einträge (null, wenn es keine gibt). Eine Gesamtanzahl wird nicht zurückgegeben. Leere Felder sind null.

ip, ip_asn, user_agent und user_agent_family sind nur vorhanden, wenn der Schlüssel die Berechtigung audit-events:read_ip besitzt, und identifier_hint nur, wenn er users:read_pii besitzt. Ohne die Berechtigung wird das Feld vollständig weggelassen (kein maskierter Wert). ip_country wird immer zurückgegeben.

{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "occurred_at": "2026-10-01T08:15:42.120Z",
      "type": "authentication.password.failed",
      "outcome": "failure",
      "reason_code": "invalid_credentials",
      "user_id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
      "org_id": null,
      "application_id": "app_01j9xk3m7q8r2s4t6v8w0y2z4b",
      "connection_id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4c",
      "directory_id": null,
      "session_id": null,
      "identifier_hint": "a***@e***.com",
      "ip": "203.0.113.7",
      "ip_country": "DE",
      "ip_asn": 64500,
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64)",
      "user_agent_family": "Firefox",
      "risk": null,
      "auth_context": null,
      "act_chain": null,
      "details": {"attempt": 3},
      "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182",
      "correlation_id": null,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": "<opaque cursor>"
  }
}

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 nicht für diese Anfrage ausgestellt.
400 invalid_filter Der Protokolldienst hat einen Filter oder den Cursor abgelehnt.
400 range_outside_retention from liegt vor dem Aufbewahrungszeitraum Ihres Tarifs.
422 validation_failed Ein Abfrageparameter ist ungültig (limit außerhalb des Bereichs, fehlerhafter Zeitstempel, to nicht nach from, mehr als 20 type-Werte, fehlerhafte ID oder IP, wiederholter Parameter).
401 unauthenticated Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
403 insufficient_permissions Der Schlüssel besitzt logs:read nicht oder verwendet ip ohne audit-events:read_ip bzw. q ohne users:read_pii (required_permissions listet auf, was die Anfrage benötigt).
429 rate_limited Das Ratenlimit wurde überschritten; berücksichtigen Sie Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut.

Beispiel

curl "https://api.eu.keenauth.com/v1/logs?type=authentication.&outcome=failure&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Personenbezogene Daten

Dieser Endpunkt enthält personenbezogene Daten: Umgebungsprotokolle. Personenbezogene Daten in den KeenAuth-APIs beschreibt, was gespeichert wird, wie lange es aufbewahrt und wie es gelöscht wird. Übermitteln Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).