Ein Audit-Export erstellen

POST /v1/audit-exports · Berechtigung audit-exports:write

Stellt einen Auftrag in die Warteschlange, der die passenden Audit-Datensätze in ein signiertes Paket schreibt, das Sie prüfen können, ohne KeenAuth vertrauen zu müssen. Der Auftrag wird mit 202 Accepted zurückgegeben. Verfolgen Sie ihn mit Einen Audit-Export abrufen und laden Sie die Datei mit Einen Audit-Export herunterladen herunter.

Nur API-Schlüssel (geheim oder eingeschränkt) können Exporte erstellen; der Auftrag speichert den Schlüssel als requested_by. Die Umgebung ergibt sich aus dem Schlüssel.

Anfrage

Idempotency-Key ist erforderlich (16 bis 64 Zeichen, A-Z a-z 0-9 _ -). Derselbe Schlüssel mit demselben Body liefert den ersten Auftrag mit Idempotent-Replayed: true zurück. Derselbe Schlüssel mit einem anderen Body schlägt mit 422 idempotency_key_reuse fehl. Die SDKs und die CLI setzen den Header für Sie.

Die Filter entsprechen denen in Audit-Ereignisse auflisten. Ein weggelassenes Feld filtert nicht. Unterschiede:

Feld Typ Beschreibung
stream string admin (Standard) oder application.
from RFC 3339 Untere Grenze, inklusive. Standardmäßig der Beginn des Aufbewahrungszeitraums. Es gibt kein Limit von 92 Tagen; ein Paket enthält höchstens 50 Millionen Zeilen (einschließlich Platzhalter).
to RFC 3339 Obere Grenze, exklusive. Standardmäßig der aktuelle Zeitpunkt; darf nicht in der Zukunft liegen.
action, category, actor_type, actor_id, target_type, target_id, org_id, outcome, request_id, correlation_id, agent_only Wie bei den Listenfiltern. Der Listenfilter client ist hier nicht verfügbar; ein Feld client schlägt mit 400 unknown_field fehl.
include_ip boolean Fügt die vollständige IP-Adresse und den User-Agent zu Datensätzen hinzu, die jünger als 13 Monate sind. Erfordert zusätzlich audit-events:read_ip. Standard false. 
{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}

Pro Umgebung laufen gleichzeitig höchstens 3 Aufträge (1 in Entwicklungs- und Staging-Umgebungen).

Antwort

202 Accepted und der Auftrag mit status queued. filter zeigt den angewendeten Filter mit den ausgefüllten Standardwerten von from und to. recorded_before ist die Snapshot-Grenze: Nur Datensätze, die davor gespeichert wurden, gelangen in das Paket.

{
  "id": "aex_01j9xk3m7q8r2s4t6v8w0y2z4e",
  "status": "queued",
  "filter": {
    "stream": "admin",
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z",
    "action": "user.",
    "category": null,
    "actor_type": null,
    "actor_id": null,
    "target_type": null,
    "target_id": null,
    "org_id": null,
    "outcome": null,
    "request_id": null,
    "correlation_id": null,
    "agent_only": false
  },
  "include_ip": false,
  "record_count": null,
  "file": null,
  "manifest_sha256": null,
  "failure_reason": null,
  "created_at": "2026-10-19T09:00:00Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "recorded_before": "2026-10-19T09:00:00Z",
  "requested_by": {"type": "api_key", "id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d"}
}

Fehler

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

HTTP code Wann
400 malformed_request Idempotency-Key fehlt oder ist fehlerhaft, oder der Body ist kein gültiges JSON.
400 unknown_field Der Body enthält ein Feld, das oben nicht aufgeführt ist.
400 invalid_filter Der Audit-Dienst hat den Filter abgelehnt, zum Beispiel weil to in der Zukunft liegt.
400 range_outside_retention from oder to liegt außerhalb des Audit-Aufbewahrungszeitraums Ihres Tarifs.
422 validation_failed Ein Feld ist ungültig (falscher Typ, fehlerhafter Zeitstempel, to nicht nach from, unbekannter Enum-Wert, fehlerhafte ID, leere Zeichenkette).
422 idempotency_key_reuse Der Idempotency-Key wurde mit einem anderen Body verwendet.
401 unauthenticated Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
403 insufficient_permissions Dem Schlüssel fehlt audit-exports:write, er verwendet include_ip ohne audit-events:read_ip (required_permissions listet beide auf), oder der Aufrufer ist kein API-Schlüssel.
429 rate_limited In dieser Umgebung laufen zu viele Aufträge, oder 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.

Beispiel

curl https://api.eu.keenauth.com/v1/audit-exports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-07-01T00:00:00Z", "to": "2026-10-01T00:00:00Z", "action": "user."}'

keenauth audit-exports create --from 2026-07-01T00:00:00Z --to 2026-10-01T00:00:00Z --action user.

Personenbezogene Daten

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