로그 목록 조회

GET /v1/logs · 권한 logs:read

환경의 로그 레코드(로그인, 세션, 토큰, MFA, 공격 방어 등)를 최신순으로 커서 페이지네이션하여 나열합니다. 요금제의 보관 기간(Free 7일, Startup 14일, Business 30일, Enterprise 90일)보다 오래된 레코드는 반환되지 않습니다.

요청

매개변수	위치	필수	설명
`limit`	query	아니요	페이지 크기, 1~100. 기본값 20.
`after`	query	아니요	`list_metadata.after`에서 얻은 불투명 커서(더 오래된 레코드). `before`와 함께 사용할 수 없습니다.
`before`	query	아니요	`list_metadata.before`에서 얻은 불투명 커서(더 최신 레코드). `after`와 함께 사용할 수 없습니다.
`from`	query	아니요	RFC 3339 시각이며, 이 시각 이후의 레코드를 반환합니다. 보관 기간 안이어야 합니다.
`to`	query	아니요	RFC 3339 시각이며, 이 시각 이전의 레코드를 반환합니다. `from`보다 이후여야 합니다.
`type`	query	아니요	`authentication.` 또는 `session.created`와 같은 로그 유형 접두사. 최대 20개 값까지 매개변수를 반복할 수 있으며, 하나라도 일치하는 레코드가 반환됩니다.
`outcome`	query	아니요	`success`, `failure`, `denied` 또는 `error`.
`user_id`, `org_id`, `application_id`, `connection_id`, `directory_id`, `session_id`	query	아니요	접두사가 붙은 ID에 대한 정확한 일치(`usr_`, `org_`, `app_`, `conn_`, `dir_`, `ses_`).
`request_id`	query	아니요	요청의 `Idp-Request-Id`(UUID). 예를 들어 호스팅된 로그인 오류 페이지에 표시되는 ID입니다.
`correlation_id`	query	아니요	워크플로의 `Idp-Correlation-Id`(UUID).
`ip`	query	아니요	IP 주소 또는 CIDR 블록(`203.0.113.0/24`). `audit-events:read_ip` 권한이 필요합니다.
`ip_country`	query	아니요	IP의 국가, 대문자 ISO 3166-1 alpha-2 코드(`DE`).
`q`	query	아니요	마스킹된 식별자 힌트의 접두사(`j***@`). `users:read_pii` 권한이 필요합니다.

레코드는 항상 occurred_at 기준으로 최신순 정렬되며, order 매개변수는 없습니다(order=desc는 허용되고, 다른 값은 validation_failed로 실패합니다). 커서는 발급된 필터와 함께 사용할 때만 유효합니다.

ip 및 q 필터는 결과를 좁히기만 하더라도 해당 권한이 필요합니다. 권한이 없으면 검색 전에 403 insufficient_permissions로 요청이 실패하므로, 키가 읽을 권한이 없는 값을 탐색할 수 없습니다.

응답

200 OK를 반환합니다. data에는 현재 페이지의 레코드가 포함되며, list_metadata.after는 더 오래된 레코드를, list_metadata.before는 더 최신 레코드를 가리킵니다(없으면 null). 전체 개수는 반환되지 않습니다. 비어 있는 필드는 null입니다.

ip, ip_asn, user_agent, user_agent_family는 키에 audit-events:read_ip 권한이 있을 때만 포함되고, identifier_hint는 users:read_pii 권한이 있을 때만 포함됩니다. 권한이 없으면 해당 필드는 마스킹된 값 없이 완전히 생략됩니다. ip_country는 항상 반환됩니다.

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

오류

모든 오류는 안정적인 code를 포함한 application/problem+json 본문으로 반환됩니다.

HTTP	`code`	발생 조건
400	`invalid_cursor`	커서 형식이 잘못되었거나 이 요청에 대해 발급되지 않았습니다.
400	`invalid_filter`	로그 서비스가 필터 또는 커서를 거부했습니다.
400	`range_outside_retention`	`from`이 요금제의 보관 기간보다 이전입니다.
422	`validation_failed`	쿼리 매개변수가 잘못되었습니다(`limit` 범위 초과, 잘못된 시각, `to`가 `from` 이후가 아님, `type` 값 20개 초과, 잘못된 ID 또는 IP 형식, 매개변수 중복).
401	`unauthenticated`	API 키가 없거나, 잘못되었거나, 취소되었습니다.
403	`insufficient_permissions`	키에 `logs:read` 권한이 없거나, `audit-events:read_ip` 없이 `ip`를 사용했거나, `users:read_pii` 없이 `q`를 사용했습니다(`required_permissions`에 요청에 필요한 권한이 나열됩니다).
429	`rate_limited`	요청 한도를 초과했습니다. `Retry-After`를 따르십시오.
503	`service_unavailable`	종속 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오.

예제

curl "https://api.eu.keenauth.com/v1/logs?type=authentication.&outcome=failure&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

개인정보

이 엔드포인트는 개인정보, 즉 환경 로그를 포함합니다. KeenAuth API의 개인정보에서 저장되는 항목, 보관 기간, 삭제 방법을 설명합니다. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 인식 데이터, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.