# 사용자 목록 조회

`GET /v1/users` · 권한 `users:read`

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

## 요청

| 파라미터 | 위치 | 필수 여부 | 설명 |
|---|---|---|---|
| `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`는 마스킹되지 않습니다.

```json
{
  "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` | 종속 서비스를 일시적으로 사용할 수 없는 경우입니다. 나중에 다시 시도하십시오. |

## 예시

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

## 개인정보

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