# ユーザーの一覧取得

`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` は先頭 1 文字のみ残ります(`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)では、保存される内容、保存期間、削除方法について説明しています。いかなるフィールドにも特別な種類の個人データ(健康、生体情報、宗教、政治的意見、性的指向)を送信しないでください。