Télécharger un export d'audit

GET /v1/audit-exports/{export_id}/download · autorisation audit-exports:read

Fournit un lien à usage unique vers le package d'un job d'export terminé. Les clés API (secrètes ou restreintes) et les utilisateurs du tableau de bord peuvent télécharger ; un téléchargement depuis le tableau de bord exige une connexion récente (étape supplémentaire, datant de 5 minutes au plus). Chaque appel écrit un enregistrement audit_export.downloaded dans le flux admin avant que le lien ne soit émis.

Requête

Paramètre	Dans	Obligatoire	Description
`export_id`	chemin	oui	Identifiant du job d'export, préfixé par `aex_`.

Un job créé avec include_ip: true exige aussi audit-events:read_ip sur la clé qui télécharge.

Réponse

La réponse dépend de l'en-tête Accept. Les deux formes contiennent Cache-Control: no-store, Referrer-Policy: no-referrer et Vary: Accept, et écrivent toutes deux le même enregistrement audit_export.downloaded.

Accept liste application/json (explicitement, avec un q non nul ; */* ne compte pas) : 200 OK avec un corps JSON. Utilisez cette forme depuis un navigateur ou tout client qui ne peut pas lire une redirection inter-origine : lisez url, puis ouvrez-le.

Champ	Type	Description
`url`	string	Lien relatif sur le même hôte, `/downloads/audit-exports/{environment_id}/{export_id}/{token}`.
`expires_at`	string (date-time)	Moment où le lien cesse de fonctionner (15 minutes après son émission).

Tout autre Accept : 302 Found avec un corps vide. Location est le même lien relatif.
Le lien est valide 15 minutes et ne fonctionne qu'une fois : le jeton est consommé à la première requête, même si le transfert est interrompu. Appelez à nouveau cette opération pour obtenir un nouveau lien.
Le lien ne demande aucune identification ; le jeton est la seule identification. Gardez Location (ou url) secret et ne le journalisez pas.
Le fichier est chiffré au repos avec la clé de l'environnement, donc aucune URL pré-signée de stockage n'est utilisée ; KeenAuth le déchiffre et le diffuse.

Suivre le lien renvoie 200 OK avec Content-Type: application/x-tar, Content-Length et Content-Disposition: attachment; filename="audit-export-aex_….tar". Le package tar contient :

Fichier	Contenu
`records.ndjson.gz`	Chaque enregistrement de chaîne de chaque heure couverte, dans l'ordre de séquence, un objet JSON par ligne : les enregistrements correspondants en entier, les autres sous forme d'espaces réservés sans contenu (`"omitted": true`) afin que la chaîne de hachage puisse être reconstruite sans les révéler.
`manifest.json`	Filtre, compteurs, empreinte du fichier et, pour chaque heure couverte, le point de contrôle signé et la preuve d'inclusion ; JSON canonique (RFC 8785).
`manifest.jws`	Signature ES256 sur `manifest.json` ; vérifiez-la avec les clés publiques de `audit-jwks.json`.

Si la connexion se termine avant que Content-Length octets n'arrivent, le package est incomplet ; jetez-le et demandez un nouveau lien. Un lien invalide, déjà utilisé ou expiré renvoie 404 not_found.

Erreurs

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

HTTP	`code`	Quand
401	`unauthenticated`	La clé API est absente, invalide ou révoquée.
403	`insufficient_permissions`	La clé ne possède pas `audit-exports:read`, le job a été créé avec `include_ip` et la clé ne possède pas `audit-events:read_ip` (`required_permissions` les liste toutes deux), ou l'appelant n'est ni une clé API ni un utilisateur du tableau de bord.
404	`not_found`	Le job n'existe pas, appartient à un autre environnement, ou l'identifiant est mal formé. Sur le lien : le jeton est invalide, déjà utilisé ou expiré.
409	`conflict`	Le job n'est pas encore terminé, ou son fichier a expiré.
429	`rate_limited`	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

curl -L -o audit-export.tar \
  https://api.eu.keenauth.com/v1/audit-exports/aex_01j9xk3m7q8r2s4t6v8w0y2z4e/download \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Avec Accept: application/json, le lien est renvoyé en JSON au lieu d'une redirection :

curl https://api.eu.keenauth.com/v1/audit-exports/aex_01j9xk3m7q8r2s4t6v8w0y2z4e/download \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Accept: application/json"

Les SDK utilisent la forme JSON et renvoient url et expires_at. La CLI lit elle-même le lien, écrit le package dans un fichier (jamais sur la sortie standard), refuse d'écraser un fichier existant et affiche la taille et le SHA-256 de ce qu'elle a écrit :

keenauth audit-exports download aex_01j9xk3m7q8r2s4t6v8w0y2z4e --file audit-export.tar

Données personnelles

Cet endpoint contient des données personnelles : des événements d'audit. Données personnelles dans les API KeenAuth décrit ce qui est stocké, combien de temps c'est conservé et comment c'est supprimé. N'envoyez pas de catégories particulières de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.