# ユーザーにフェデレーテッドIDを紐付ける

`POST /v1/users/{user_id}/identities` · 権限 `users:write`

フェデレーテッドID（ソーシャル、SAML、OIDC接続の外部サブジェクト）をユーザーに紐付け、そのユーザーがその接続でサインインできるようにします。`linked_via` は常に `admin_api` です。接続は、この環境の有効な接続であり、その種類が `type` と一致している必要があります。同じIDがこのユーザーまたは別のユーザーにすでに紐付けられている場合、リクエストは `409` で失敗し、所有者は明らかにされません。外部サブジェクトは個人データであり、暗号化して保存され、返却されることはありません。また、管理監査レコード `user.identity_linked`（アクター: APIキー）にも含まれません。2人のユーザーの統合（`source_user_id`）は利用できません。未知のフィールドは `400 unknown_field` を返します。

## リクエスト

| パラメーター | 位置 | 必須 | 説明 |
|---|---|---|---|
| `user_id` | パス | はい | ユーザーID。`usr_` で始まります。 |

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `type` | 文字列 | はい | `social`、`saml`、`oidc` のいずれか。接続と一致している必要があります（ソーシャル接続には `social`、同じstrategyのエンタープライズ接続には `saml` または `oidc`）。 |
| `connection_id` | 文字列 | はい | 接続ID。`conn_` で始まります。 |
| `subject` | 文字列 | はい | ID プロバイダ上の外部サブジェクト（OIDC の `sub`、SAML の NameID）。UTF-8で1024バイト以内。 |

## レスポンス

`201 Created` と、新しいIDを返します。形式は `GET /v1/users/{user_id}/identities` が返すものと同じです。

```json
{
  "id": "idn_0a1b2c3d4e5f6g7h8j9k0m1n2r",
  "type": "oidc",
  "connection_id": "conn_0a1b2c3d4e5f6g7h8j9k0m1n2s",
  "provider": null,
  "linked_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z"
}
```

## エラー

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

| HTTP | `code` | 発生条件 |
|---|---|---|
| 400 | `malformed_request`、`unknown_field` | ボディが有効なJSONではないか、未知のフィールドが含まれています。 |
| 409 | `conflict` | IDがすでにユーザーに紐付けられています（`errors[]`: `identity_already_linked`）。または、ユーザーがユーザーごとのID上限に達しています（`errors[]`: `identity_limit_reached`）。 |
| 415 | `unsupported_media_type` | `Content-Type: application/json` なしでボディが送信されました。 |
| 422 | `validation_failed` | フィールドが欠けているか無効です（`/type`、`/connection_id`、`/subject`）。または、接続が `type` に一致するこの環境の有効な接続ではありません（`errors[]`: `/connection_id`、`connection_unavailable`）。 |
| 404 | `not_found` | ユーザーがこの環境に存在しないか、削除中であるか、IDの形式が不正です。 |
| 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/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/identities \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "oidc", "connection_id": "conn_0a1b2c3d4e5f6g7h8j9k0m1n2s", "subject": "248289761001"}'
```

## 個人データ

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