Listar eventos de auditoría

GET /v1/audit-events · permiso audit-events:read

Lista los registros de auditoría del entorno con paginación por cursor, del más reciente al más antiguo. El flujo admin contiene los cambios realizados mediante la API de gestión, el panel de control y la plataforma; el flujo application contiene los eventos que escribió su aplicación. Cada registro forma parte de una cadena de hash por entorno y flujo, por lo que el historial puede verificarse de forma independiente con una exportación (POST /v1/audit-exports).

El entorno siempre se obtiene de la clave de API; no existe un parámetro de entorno.

Solicitud

Parámetro En Obligatorio Descripción
limit query no Tamaño de página, de 1 a 100. Por defecto, 20.
after query no Cursor opaco de list_metadata.after (registros más antiguos). Excluyente con before.
before query no Cursor opaco de list_metadata.before (registros más recientes). Excluyente con after.
stream query no admin (por defecto) o application.
from query no Hora RFC 3339; registros en esa hora o posteriores. Por defecto, la más tardía entre el inicio del periodo de retención y to menos 92 días.
to query no Hora RFC 3339; registros anteriores a ella. Por defecto, el momento actual. El intervalo entre from y to es de 92 días como máximo.
action query no Prefijo de acción, como user. o connection.updated.
category query no authentication, session, token, administration, provisioning, federation, authorization, data_access, security, key_management, configuration o application.
actor_type query no Tipo de actor, como api_key, dashboard_user, m2m_client, agent o system.
actor_id query no Id exacto del actor tal como se registró (key_…, usr_…, system:<service>).
target_type query no Tipo de objetivo, como user, organization o audit_export.
target_id query no Id exacto del objetivo. Con target_type, ambos deben coincidir con el mismo objetivo.
org_id query no Registros sobre una organización (org_…).
outcome query no success, failure, denied o error.
request_id query no Idp-Request-Id de una petición (UUID).
correlation_id query no Idp-Correlation-Id de un flujo de trabajo (UUID).
agent_only query no true devuelve solo las acciones de agentes: actor_type agent o un act_chain no vacío.
client query no Tipo de cliente que realizó la llamada: mcp (el servidor MCP de gestión, metadata.client = mcp/<version>) o cli (la CLI de KeenAuth, cli/<version>). El cliente declara este valor por sí mismo; no es una prueba de quién actuó, para eso está el actor del registro. Solo para listados: una exportación no tiene filtro client.

Los registros siempre se ordenan por occurred_at (y luego por id), del más reciente al más antiguo; no existe un parámetro order (se acepta order=desc, cualquier otro valor falla con validation_failed). Un cursor solo es válido con los filtros y el entorno para los que se emitió. No se devuelve un recuento total.

Una búsqueda que tarde más de 10 segundos se detiene con 422 search_too_broad: restrinja los filtros o el intervalo de tiempo, o use una exportación para intervalos grandes.

Respuesta

200 OK. data contiene los registros de la página; list_metadata.after apunta a registros más antiguos y list_metadata.before a registros más recientes (null cuando no hay ninguno). Los campos vacíos son null.

ip y user_agent solo aparecen cuando la clave tiene el permiso audit-events:read_ip, y solo se rellenan para registros de menos de 13 meses. Sin ese permiso, los campos se omiten por completo (no se devuelve ningún valor enmascarado). ip_prefix, ip_country, ip_asn y user_agent_family siempre se devuelven. prev_hash, org_prev_hash y record_hash son valores SHA-256 en base64url sin relleno.

{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "stream": "admin",
      "seq": 4182,
      "schema_version": 1,
      "action": "user.blocked",
      "category": "administration",
      "outcome": "success",
      "reason_code": null,
      "occurred_at": "2026-10-01T08:15:42.120Z",
      "received_at": "2026-10-01T08:15:42.131Z",
      "recorded_at": "2026-10-01T08:15:42.140Z",
      "clock_anomaly": false,
      "actor_type": "api_key",
      "actor_id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d",
      "act_chain": null,
      "session_id": null,
      "auth_context": null,
      "elevation_ref": null,
      "org_id": null,
      "targets": [
        {"type": "user", "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p", "org_id": null, "name": null}
      ],
      "application_id": null,
      "ip_prefix": "203.0.113.0/24",
      "ip_country": "DE",
      "ip_asn": 64500,
      "user_agent_family": "keenauth-go",
      "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182",
      "correlation_id": null,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "producer_service": "directory",
      "policy_ref": "perm:users:write",
      "changes": {"status": {"old": "active", "new": "blocked"}},
      "metadata": null,
      "prev_hash": "n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg",
      "org_prev_hash": null,
      "record_hash": "LCa0a2j_xo_5m0U8HTBBNBNCLXBkg7-g-YpeiGJm564"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": "<opaque cursor>"
  }
}

Errores

Cada error es un cuerpo application/problem+json con un code estable.

HTTP code Cuándo
400 invalid_cursor El cursor tiene un formato incorrecto o no se emitió para esta petición.
400 invalid_filter El servicio de auditoría rechazó un filtro, por ejemplo un intervalo de más de 92 días.
400 range_outside_retention from o to están fuera del periodo de retención de auditoría de su plan.
422 validation_failed Un parámetro de consulta no es válido (limit fuera de rango, marca de tiempo incorrecta, to no posterior a from, stream, category u outcome desconocidos, id con formato incorrecto, parámetro repetido, order distinto de desc).
422 search_too_broad La búsqueda tardó más de 10 segundos; restrínjala.
401 unauthenticated Falta la clave de API, no es válida o ha sido revocada.
403 insufficient_permissions La clave no tiene audit-events:read.
429 rate_limited Se ha superado el límite de peticiones; 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-events?action=user.&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

keenauth audit-events list --action user. --from 2026-10-01T00:00:00Z

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.