Exporta el log de auditoría de tu equipo a NDJSON, CSV o JSON para cumplimiento, archivado y análisis posterior.
Qué contiene el log de auditoría
Cada acción que cambia el estado de la cuenta — invitaciones, cambios de rol, rotaciones de claves, ajustes de sitios, cambios de facturación y más — se registra con:
- id — id único de la entrada del log
- action — qué ocurrió (p. ej.
team.invite_member,website.update_settings) - resource_type + resource_id — sobre qué se actuó
- actor_id — qué miembro del equipo realizó la acción
- metadata — contexto adicional (origen, IP hasheada, etc.)
- created_at — marca de tiempo en UTC
Las direcciones IP dentro de metadata se almacenan como hashes unidireccionales con un salt rotado diariamente, por lo que conservas el valor forense sin exponer las IP en bruto.
También puedes examinar el mismo registro de auditoría en el panel bajo Ajustes → Seguridad → Audit log.
Disponibilidad por plan
La exportación de auditoría está disponible desde el plan Pro. (Los planes gratuitos no incluyen la creación de claves API, por lo que el endpoint no es accesible en Free.)
Autenticación
El endpoint forma parte de la External API y se llama con una clave API:
Authorization: Bearer YOUR_API_KEY
Genera una clave API desde el panel: Ajustes → Seguridad → API Keys → Nueva clave. Una clave de acceso completo funciona contra cada endpoint.
Si tu cuenta pertenece a varios equipos, dirígete a un equipo específico con el encabezado X-Zenovay-Team-Id en cada solicitud.
Exportar el log de auditoría
curl -L "https://api.zenovay.com/v1/cli/mutate/audit/export?format=ndjson" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o zenovay-audit.ndjson
Formatos admitidos
format | Content-Type | Ideal para |
|---|---|---|
ndjson (predeterminado) | application/x-ndjson | Streaming hacia pipelines de análisis de logs (JSON delimitado por líneas) |
csv | text/csv | Abrir en Excel, Google Sheets o herramientas de BI |
json | application/json | Array JSON único para procesamiento programático |
La respuesta se envía con Content-Disposition: attachment; filename="zenovay-audit.<format>" para que la mayoría de los clientes HTTP la guarden en disco.
La exportación cubre el historial de auditoría disponible de tu equipo (los audit logs se conservan durante 24 meses). Un único export devuelve hasta 10.000 de las entradas más recientes. Para archivos más grandes, ejecuta exports regulares según una programación y añádelos al almacenamiento en frío. Para búsquedas más ligeras e interactivas, usa /v1/cli/mutate/audit/logs (ver a continuación).
Recuperar entradas recientes (paginado)
Para consultas interactivas, usa /v1/cli/mutate/audit/logs:
curl "https://api.zenovay.com/v1/cli/mutate/audit/logs?since=7d&limit=100" \
-H "Authorization: Bearer YOUR_API_KEY"
Parámetros de consulta
| Parámetro | Predeterminado | Notas |
|---|---|---|
since | 7d | Ventana temporal: 1h, 7d, 4w, 12m |
action | – | Filtrar por cadena de acción exacta |
actor | – | Filtrar por id de usuario |
limit | 50 | Máximo 200 por petición |
La respuesta incluye pagination.next_cursor cuando hay más entradas más allá del limit solicitado. Para alcanzar entradas más antiguas, aumenta limit (hasta 200) o reduce la ventana since. Para un archivo completo, usa el endpoint de export anterior, que devuelve hasta 10.000 de las entradas más recientes en una sola llamada.
Mejores prácticas
- Programa exportaciones periódicas. Un cron job semanal que almacene el NDJSON en cold storage (S3 Glacier, R2, etc.) es una forma económica de mantener un rastro inmutable.
- Rota tu clave API periódicamente y tras la baja de cualquier miembro del equipo.
- Trata las exportaciones como sensibles. Las entradas no son secretos, pero describen actividad operativa — mantenlas fuera de buckets públicos y unidades compartidas.
- Combínalo con webhooks para reaccionar a acciones específicas en tiempo real y usa la exportación como reconciliación completa periódica.
Errores que podrías ver
| Estado | Significado |
|---|---|
401 unauthorized | Clave API faltante o inválida, o la clave no está asociada a un equipo |
402 upgrade_required | Tu plan no incluye la exportación de auditoría — actualiza a Pro o superior |
400 invalid_format | format debe ser uno de ndjson, csv, json |
Cada respuesta también incluye el encabezado x-request-id. Consérvalo en tus tickets de soporte para que podamos rastrear la llamada de extremo a extremo.