사용자 검색

POST /v1/users:search · 권한 users:read

개인 정보가 포함된 필터로 사용자를 검색합니다. 이 필터는 요청 본문에서만 허용되며, 쿼리 문자열에서는 사용할 수 없습니다. 쿼리 문자열은 프록시 및 클라이언트 로그에 남기 때문입니다. 필터는 AND로 결합되며, 최소 하나의 식별 필터가 필요합니다. 일치 방식은 정확 일치이며, 접두사 검색과 부분 문자열 검색은 제공하지 않습니다. 너무 많은 사용자와 일치하는 검색은 search_too_broad로 실패하므로 필터를 좁혀 주십시오.

요청

페이지네이션 매개변수는 쿼리 문자열에 넣습니다. 이 매개변수에는 개인 정보가 포함되지 않습니다.

매개변수 위치 필수 설명
limit query 아니요 페이지 크기, 1~100. 기본값은 20입니다.
after query 아니요 list_metadata.after에서 받은 불투명 커서입니다. before와 함께 사용할 수 없습니다.
before query 아니요 list_metadata.before에서 받은 불투명 커서입니다. after와 함께 사용할 수 없습니다.
order query 아니요 생성 시각 기준 asc 또는 desc. 기본값은 desc입니다.

본문 필드:

필드 유형 필수 설명
email string 아니요 정확한 이메일 주소입니다.
phone string 아니요 E.164 형식의 정확한 전화번호입니다.
username string 아니요 정확한 사용자 이름입니다.
email_domain string 아니요 정확한 이메일 도메인입니다.
app_metadata, user_metadata object 아니요 최상위 키는 최대 3개이며, 각 키는 스칼라 값과 정확히 일치해야 합니다.
status string 아니요 active, blocked 또는 pending_deletion.

커서는 발급된 것과 동일한 필터 집합 및 정렬 순서에서만 유효합니다.

응답

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는 마스킹되지 않습니다. users:read_pii 권한이 없는 키도 정확 일치 개인 정보 필터로 검색할 수 있으며, 결과는 마스킹되어 반환됩니다.

{
  "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 unknown_field, invalid_cursor 본문에 지원되지 않는 필드(예: 접두사 필터)가 있거나, 커서가 요청과 일치하지 않습니다.
415 unsupported_media_type Content-Type이 application/json이 아닙니다.
422 validation_failed, search_too_broad 필터가 유효하지 않거나, 식별 필터가 없거나, 검색 결과가 너무 많은 사용자와 일치합니다.
401 unauthenticated API 키가 없거나 유효하지 않거나 폐기되었습니다.
403 insufficient_permissions 키에 users:read 권한이 없습니다.
429 rate_limited 요청 한도를 초과했습니다. Retry-After를 따르십시오.
503 service_unavailable 종속 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오.

예제

curl -X POST "https://api.eu.keenauth.com/v1/users:search?limit=20" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com"}'

개인 정보

이 엔드포인트는 개인 정보를 다룹니다. 최종 사용자 프로필이 포함됩니다. KeenAuth API의 개인 정보에서 저장되는 항목, 보관 기간, 삭제 방법을 확인할 수 있습니다. 어떤 필드에도 특수 범주의 개인 정보(건강, 생체 정보, 종교, 정치적 견해, 성적 指向)를 보내지 마십시오.