Listar logs

GET /v1/logs · permiso logs:read

Lista los registros de log del entorno (inicios de sesión, sesiones, tokens, MFA, protección contra ataques y más) con paginación por cursor, del más reciente al más antiguo. Los registros más antiguos que el periodo de retención de su plan (Free 7, Startup 14, Business 30, Enterprise 90 días) nunca se devuelven.

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`.
`from`	query	no	Hora RFC 3339; registros en esa hora o posteriores. Debe estar dentro del periodo de retención.
`to`	query	no	Hora RFC 3339; registros anteriores a esa hora. Debe ser posterior a `from`.
`type`	query	no	Prefijo del tipo de log, como `authentication.` o `session.created`. Repita el parámetro para hasta 20 valores; se devuelve un registro que coincida con cualquiera de ellos.
`outcome`	query	no	`success`, `failure`, `denied` o `error`.
`user_id`, `org_id`, `application_id`, `connection_id`, `directory_id`, `session_id`	query	no	Coincidencia exacta con el id prefijado (`usr_`, `org_`, `app_`, `conn_`, `dir_`, `ses_`).
`request_id`	query	no	`Idp-Request-Id` de una solicitud (UUID), por ejemplo el id que se muestra en una página de error de inicio de sesión alojada.
`correlation_id`	query	no	`Idp-Correlation-Id` de un flujo de trabajo (UUID).
`ip`	query	no	Dirección IP o bloque CIDR (`203.0.113.0/24`). Requiere `audit-events:read_ip`.
`ip_country`	query	no	País de la IP, ISO 3166-1 alpha-2 en mayúsculas (`DE`).
`q`	query	no	Prefijo de la pista del identificador enmascarado (`j***@`). Requiere `users:read_pii`.

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

Los filtros ip y q necesitan su permiso aunque solo restrinjan el resultado: sin él, la solicitud falla con 403 insufficient_permissions antes de cualquier búsqueda, de modo que una clave no puede sondear valores que no tiene permiso para leer.

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). No se devuelve un recuento total. Los campos vacíos son null.

ip, ip_asn, user_agent y user_agent_family solo se incluyen cuando la clave tiene el permiso audit-events:read_ip, y identifier_hint solo cuando tiene users:read_pii. Sin el permiso, el campo se omite por completo (no se devuelve ningún valor enmascarado). ip_country se devuelve siempre.

{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "occurred_at": "2026-10-01T08:15:42.120Z",
      "type": "authentication.password.failed",
      "outcome": "failure",
      "reason_code": "invalid_credentials",
      "user_id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
      "org_id": null,
      "application_id": "app_01j9xk3m7q8r2s4t6v8w0y2z4b",
      "connection_id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4c",
      "directory_id": null,
      "session_id": null,
      "identifier_hint": "a***@e***.com",
      "ip": "203.0.113.7",
      "ip_country": "DE",
      "ip_asn": 64500,
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64)",
      "user_agent_family": "Firefox",
      "risk": null,
      "auth_context": null,
      "act_chain": null,
      "details": {"attempt": 3},
      "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182",
      "correlation_id": null,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": "<opaque cursor>"
  }
}

Errores

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

HTTP	`code`	Cuándo
400	`invalid_cursor`	El cursor está mal formado o no se emitió para esta solicitud.
400	`invalid_filter`	El servicio de logs rechazó un filtro o el cursor.
400	`range_outside_retention`	`from` es anterior al periodo de retención 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`, más de 20 valores de `type`, id o IP mal formados, parámetro repetido).
401	`unauthenticated`	Falta la clave de API, no es válida o ha sido revocada.
403	`insufficient_permissions`	La clave no tiene `logs:read`, o usa `ip` sin `audit-events:read_ip` o `q` sin `users:read_pii` (`required_permissions` indica lo que necesita la solicitud).
429	`rate_limited`	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/logs?type=authentication.&outcome=failure&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Datos personales

Este endpoint contiene datos personales: logs del entorno. Datos personales en las API de KeenAuth describe qué se almacena, durante 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.