사용자 목록 조회

GET /v1/users · 권한 users:read

환경의 사용자 목록을 커서 페이지네이션으로 조회합니다. 기본적으로 최신순으로 정렬됩니다. 개인정보가 포함되지 않은 필터만 이 엔드포인트에서 허용됩니다. 이메일 주소, 전화번호 또는 사용자 이름으로 사용자를 찾으려면 사용자 검색을 사용하십시오.

요청

파라미터 위치 필수 여부 설명
limit query 아니요 페이지 크기이며 1에서 100 사이입니다. 기본값은 20입니다.
after query 아니요 list_metadata.after에서 받은 불투명 커서입니다. before와 함께 사용할 수 없습니다.
before query 아니요 list_metadata.before에서 받은 불투명 커서입니다. after와 함께 사용할 수 없습니다.
order query 아니요 생성 시각 기준 asc 또는 desc입니다. 기본값은 desc입니다.
status query 아니요 active, blocked 또는 pending_deletion입니다.
external_id query 아니요 귀사의 식별자와 정확히 일치하는 값입니다.
created_after query 아니요 RFC 3339 시각이며, 이 시각 이후에 생성된 사용자를 조회합니다.
created_before query 아니요 RFC 3339 시각이며, 이 시각 이전에 생성된 사용자를 조회합니다.

커서는 발급된 것과 동일한 필터 및 정렬 조건으로 요청할 때만 유효합니다. 그렇지 않으면 요청이 invalid_cursor와 함께 실패합니다.

응답

200 OK. data에는 현재 페이지의 사용자가 담깁니다. list_metadata.before와 list_metadata.after는 이전 페이지와 다음 페이지의 커서이며, 해당 페이지가 없으면 null입니다. 전체 개수는 반환되지 않습니다.

키에 users:read_pii 권한이 없으면 개인정보가 마스킹됩니다. email은 a***@e***.com으로 바뀌고, phone_number는 마지막 2자리만 유지됩니다(+**********67). name, given_name, family_name, middle_name, nickname은 이니셜로 바뀌고(A. L.), username은 첫 글자만 유지됩니다(a***). birthdate는 ****-**-**로, address는 {"redacted": true}로 바뀝니다. user_metadata와 app_metadata는 마스킹되지 않습니다.

{
  "data": [ {
    "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
    "kind": "regular",
    "status": "active",
    "external_id": null,
    "username": null,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "email_verified": true,
    "phone_number": null,
    "phone_verified": false,
    "user_metadata": {},
    "app_metadata": {},
    "created_via": "admin_api",
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:30:00Z",
    "last_sign_in_at": null,
    "deletion_requested_at": null,
    "deletion_due_at": null
  } ],
  "list_metadata": { "before": null, "after": "<opaque cursor>" }
}

오류

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

HTTP code 발생 조건
400 invalid_cursor 커서의 형식이 잘못되었거나, 변조되었거나, 다른 필터로 발급된 경우입니다.
422 validation_failed 쿼리 파라미터가 올바르지 않은 경우입니다(limit 범위 초과, 잘못된 시각, 파라미터 중복).
401 unauthenticated API 키가 없거나, 유효하지 않거나, 폐기된 경우입니다.
403 insufficient_permissions 키에 users:read 권한이 없는 경우입니다.
429 rate_limited 호출 한도를 초과한 경우입니다. Retry-After 값을 따르십시오.
503 service_unavailable 종속 서비스를 일시적으로 사용할 수 없는 경우입니다. 나중에 다시 시도하십시오.

예시

curl "https://api.eu.keenauth.com/v1/users?limit=20&status=active" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

개인정보

이 엔드포인트는 개인정보를 다룹니다. 대상은 최종 사용자의 프로필입니다. KeenAuth API의 개인정보에서 저장되는 정보, 보관 기간, 삭제 방법을 확인하십시오. 어떤 필드에도 민감정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.