Crear una exportación de auditoría

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

Pone en cola un trabajo que escribe los registros de auditoría coincidentes en un paquete firmado que puede verificar sin confiar en KeenAuth. El trabajo se devuelve con 202 Accepted; haga seguimiento con Obtener una exportación de auditoría y descargue el archivo con Descargar una exportación de auditoría.

Solo las claves de API (secretas o restringidas) pueden crear exportaciones; el trabajo registra la clave como requested_by. El entorno se toma de la clave.

Solicitud

Idempotency-Key es obligatorio (de 16 a 64 caracteres, A-Z a-z 0-9 _ -). La misma clave con el mismo cuerpo devuelve el primer trabajo con Idempotent-Replayed: true; la misma clave con un cuerpo distinto falla con 422 idempotency_key_reuse. Los SDK y la CLI establecen el encabezado por usted.

Los filtros son los mismos que en Listar eventos de auditoría; un campo omitido no filtra. Diferencias:

Campo Tipo Descripción
stream string admin (predeterminado) o application.
from RFC 3339 Límite inferior inclusivo. Por defecto, el inicio de la ventana de retención. No hay límite de 92 días; un paquete contiene como máximo 50 millones de líneas (incluidos los marcadores de posición).
to RFC 3339 Límite superior exclusivo. Por defecto, el momento actual; no puede estar en el futuro.
action, category, actor_type, actor_id, target_type, target_id, org_id, outcome, request_id, correlation_id, agent_only Igual que en los filtros de la lista. El filtro client de la lista no está disponible aquí; un campo client falla con 400 unknown_field.
include_ip boolean Añade la dirección IP completa y el user agent a los registros con menos de 13 meses. También requiere audit-events:read_ip. Predeterminado false. 
{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}

Como máximo se ejecutan 3 trabajos al mismo tiempo por entorno (1 en los entornos de desarrollo y staging).

Respuesta

202 Accepted y el trabajo con status queued. filter muestra el filtro aplicado con los valores predeterminados de from y to completados. recorded_before es el límite de la instantánea: solo entran en el paquete los registros almacenados antes de él.

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

Errores

Todos los errores son un cuerpo application/problem+json con un code estable.

HTTP code Cuándo
400 malformed_request Falta Idempotency-Key o tiene un formato incorrecto, o el cuerpo no es JSON válido.
400 unknown_field El cuerpo tiene un campo que no aparece en la lista anterior.
400 invalid_filter El servicio de auditoría rechazó el filtro, por ejemplo to en el futuro.
400 range_outside_retention from o to están fuera de la ventana de retención de auditoría de su plan.
422 validation_failed Un campo no es válido (tipo incorrecto, marca de tiempo errónea, to no posterior a from, valor de enumeración desconocido, id con formato incorrecto, cadena vacía).
422 idempotency_key_reuse Idempotency-Key se usó con un cuerpo distinto.
401 unauthenticated La clave de API falta, no es válida o fue revocada.
403 insufficient_permissions La clave no tiene audit-exports:write, usa include_ip sin audit-events:read_ip (required_permissions enumera ambos), o quien llama no es una clave de API.
429 rate_limited Hay demasiados trabajos en ejecución en este entorno, o se superó el límite de frecuencia; respete Retry-After.
503 service_unavailable Una dependencia no está disponible temporalmente; reintente más tarde.

Ejemplo

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.

Datos personales

Este endpoint contiene datos personales: eventos de auditoría. Datos personales en las API de KeenAuth describe qué se almacena, cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.