# Créer un export d'audit

`POST /v1/audit-exports` · autorisation `audit-exports:write`

Met en file d'attente une tâche qui écrit les enregistrements d'audit correspondants dans un paquet signé que vous pouvez vérifier sans faire confiance à KeenAuth. La tâche est renvoyée avec `202 Accepted` ; suivez-la avec [Obtenir un export d'audit](get.md) et récupérez le fichier avec [Télécharger un export d'audit](download.md).

Seules les clés d'API (secrète ou restreinte) peuvent créer des exports ; la tâche enregistre la clé comme `requested_by`. L'environnement provient de la clé.

## Requête

`Idempotency-Key` est obligatoire (16 à 64 caractères, `A-Z a-z 0-9 _ -`). La même clé avec le même corps renvoie la première tâche avec `Idempotent-Replayed: true` ; la même clé avec un corps différent échoue avec `422 idempotency_key_reuse`. Les SDK et la CLI définissent cet en-tête à votre place.

Les filtres sont les mêmes que dans [Lister les événements d'audit](../audit-events/list.md) ; un champ omis ne filtre pas. Différences :

| Champ | Type | Description |
|---|---|---|
| `stream` | string | `admin` (par défaut) ou `application`. |
| `from` | RFC 3339 | Borne inférieure incluse. Par défaut, le début de la fenêtre de conservation. Il n'existe pas de limite de 92 jours ; un paquet contient au maximum 50 millions de lignes (espaces réservés inclus). |
| `to` | RFC 3339 | Borne supérieure exclue. Par défaut, l'instant présent ; ne peut pas être dans le futur. |
| `action`, `category`, `actor_type`, `actor_id`, `target_type`, `target_id`, `org_id`, `outcome`, `request_id`, `correlation_id`, `agent_only` | | Comme dans les filtres de liste. Le filtre `client` de la liste n'est pas disponible ici ; un champ `client` échoue avec `400 unknown_field`. |
| `include_ip` | boolean | Ajoute l'adresse IP complète et l'agent utilisateur aux enregistrements de moins de 13 mois. Exige également `audit-events:read_ip`. Par défaut `false`. |

```json
{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}
```

Au maximum 3 tâches s'exécutent en même temps par environnement (1 dans les environnements de développement et de préproduction).

## Réponse

`202 Accepted` et la tâche avec `status` `queued`. `filter` affiche le filtre appliqué, avec les valeurs par défaut de `from` et `to` renseignées. `recorded_before` est la borne de l'instantané : seuls les enregistrements stockés avant cette date entrent dans le paquet.

```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"}
}
```

## Erreurs

Chaque erreur est un corps `application/problem+json` avec un `code` stable.

| HTTP | `code` | Quand |
|---|---|---|
| 400 | `malformed_request` | `Idempotency-Key` est absent ou mal formé, ou le corps n'est pas du JSON valide. |
| 400 | `unknown_field` | Le corps contient un champ qui ne figure pas dans la liste ci-dessus. |
| 400 | `invalid_filter` | Le service d'audit a rejeté le filtre, par exemple `to` dans le futur. |
| 400 | `range_outside_retention` | `from` ou `to` est en dehors de la fenêtre de conservation de l'audit de votre offre. |
| 422 | `validation_failed` | Un champ est invalide (mauvais type, horodatage incorrect, `to` non postérieur à `from`, valeur d'énumération inconnue, identifiant mal formé, chaîne vide). |
| 422 | `idempotency_key_reuse` | La `Idempotency-Key` a été utilisée avec un corps différent. |
| 401 | `unauthenticated` | La clé d'API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne dispose pas de `audit-exports:write`, utilise `include_ip` sans `audit-events:read_ip` (`required_permissions` liste les deux), ou l'appelant n'est pas une clé d'API. |
| 429 | `rate_limited` | Trop de tâches sont en cours dans cet environnement, ou la limite de débit a été dépassée ; respectez `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez plus tard. |

## Exemple

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

## Données personnelles

Cet point de terminaison contient des données personnelles : des événements d'audit. [Données personnelles dans les API KeenAuth](/docs/policies/personal-data) décrit ce qui est stocké, pendant combien de temps et comment elles sont supprimées. N'envoyez aucune donnée personnelle sensible (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.