# 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](get.md) und laden Sie die Datei mit [Einen Audit-Export herunterladen](download.md) 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](../audit-events/list.md). 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`. |

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

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

```bash
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."}'
```

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