# ユーザーを作成

`POST /v1/users` · 権限 `users:write`

API キーの環境にユーザーを作成します。ユーザーはその環境にのみ属します。同じメールアドレスでも、2 つの環境にあれば別々のユーザーになります。一意の値（`email`、`phone_number`、`username`、`external_id`）は環境ごとにチェックされます。再試行を安全に行うには `Idempotency-Key` ヘッダーを送信してください。

## リクエスト

ボディは JSON オブジェクトです。スキーマにないフィールドがあると、`unknown_field` で拒否されます。

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `email` | string | いいえ* | 主要メールアドレス。 |
| `email_verified` | boolean | いいえ | メールアドレスを確認済みとしてマークします。既定値は `false`。 |
| `phone_number` | string | いいえ* | E.164 形式の主要電話番号。 |
| `phone_verified` | boolean | いいえ | 電話番号を確認済みとしてマークします。既定値は `false`。 |
| `phone_country_code` | string | いいえ | ISO 3166-1 alpha-2 コード。空の場合は電話番号のプレフィックスから導出されます。 |
| `username` | string | いいえ* | 3〜64 文字。環境内で一意である必要があります。 |
| `external_id` | string | いいえ | お客様独自の識別子。1〜255 文字。環境内で一意である必要があります。 |
| `name`、`given_name`、`family_name`、`middle_name`、`nickname` | string | いいえ | プロフィールの名前。 |
| `picture`、`website`、`profile_url` | string | いいえ | `https://` の URL。最大 2048 文字。 |
| `locale`、`zoneinfo`、`gender`、`birthdate` | string | いいえ | プロフィール属性。`birthdate` は `YYYY-MM-DD` 形式です。 |
| `address` | object | いいえ | OIDC の `address` オブジェクト。最大 2048 バイト。 |
| `user_metadata`、`app_metadata` | object | いいえ | 自由形式の JSON オブジェクト。最大 16 KiB、深さ 5、トップレベルのキーは 100 個まで。 |

\* `email`、`phone_number`、`username` のうち少なくとも 1 つが必要です。

## レスポンス

`201 Created`。ボディはユーザーオブジェクトです。`ETag` ヘッダーにはユーザーのバージョンが含まれます。

API キーに `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
{
  "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
}
```

## エラー

すべてのエラーは、安定した `code` を含む `application/problem+json` ボディで返されます。

| HTTP | `code` | 発生条件 |
|---|---|---|
| 400 | `malformed_request`、`unknown_field` | ボディが有効な JSON ではない、またはスキーマにないフィールドがある。 |
| 409 | `conflict` | 値がすでに使用されている。`errors[]` にフィールドと理由（`email_taken`、`phone_taken`、`username_taken`、`external_id_taken`）が示されます。 |
| 415 | `unsupported_media_type` | `Content-Type` が `application/json` ではない。 |
| 422 | `validation_failed` | 値が無効。`errors[].pointer` にフィールドが示されます。 |
| 401 | `unauthenticated` | API キーが存在しない、無効、または取り消されている。 |
| 403 | `insufficient_permissions` | キーに `users:write` 権限がない。 |
| 429 | `rate_limited` | レート制限を超えた。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | 依存サービスが一時的に利用できない。後で再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/users \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email": "ada@example.com", "email_verified": true, "name": "Ada Lovelace"}'
```

## 個人データ

このエンドポイントは個人データを扱います：エンドユーザーのプロフィール。[KeenAuth APIs の個人データ](/docs/policies/personal-data)では、保存される内容、保存期間、削除方法について説明しています。どのフィールドにも、特別な種類の個人データ（健康、生体データ、宗教、政治的意見、性的指向）を送信しないでください。