# ユーザーを検索

`POST /v1/users:search` · 権限 `users:read`

個人データを含むフィルターを使用してユーザーを検索します。これらのフィルターはリクエストボディでのみ受け付け、クエリ文字列では受け付けません。クエリ文字列はプロキシやクライアントのログに残るためです。フィルターは AND で組み合わせられ、ID に関するフィルターを少なくとも 1 つ指定する必要があります。一致は完全一致のみです。前方一致や部分一致による検索は提供していません。一致するユーザーが多すぎる検索は `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` は先頭 1 文字のみが残ります(`a***`)。`birthdate` は `****-**-**` になり、`address` は `{"redacted": true}` になります。`user_metadata` と `app_metadata` はマスクされません。`users:read_pii` 権限のないキーでも、個人データの完全一致フィルターを使って検索できます。その場合、結果はマスクされます。

```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 | `unknown_field`, `invalid_cursor` | ボディに未対応のフィールドがある(例: 前方一致フィルター)、またはカーソルがリクエストと一致しない。 |
| 415 | `unsupported_media_type` | `Content-Type` が `application/json` ではない。 |
| 422 | `validation_failed`, `search_too_broad` | フィルターが無効、ID に関するフィルターが指定されていない、または一致するユーザーが多すぎる。 |
| 401 | `unauthenticated` | API キーが未指定、無効、または取り消されている。 |
| 403 | `insufficient_permissions` | キーに `users:read` 権限がない。 |
| 429 | `rate_limited` | レート制限を超えた。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | 依存するサービスが一時的に利用できない。後で再試行してください。 |

## 例

```bash
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 における個人データ](/docs/policies/personal-data)では、保存される内容、保存期間、削除方法を説明しています。どのフィールドにも、特別な種類の個人データ(健康、生体データ、宗教、政治的意見、性的指向)を送信しないでください。