# 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.

```json
{
  "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

```bash
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](/docs/policies/personal-data) 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).