# ユーザーの直接ロールを置き換える

`PUT /v1/users/{user_id}/roles` · 権限 `users:write`

ユーザーの直接の環境ロールを `role_ids` で置き換えます（完全なセット、最大 50 件。空の配列を指定するとすべて削除されます）。組織ロールは直接割り当てできません。組織メンバーシップを通じて割り当ててください。同じセットを再度書き込んでも何も変わりません。変更があると、ユーザーのリフレッシュトークンファミリーに `roles_changed` が付与され、次のリフレッシュで新しいロールが反映されます。また、`change=roles` を付けて `user.updated` として監査されます。セットに特権ロール（`is_privileged`）が含まれる場合（新たに追加されたものでも、維持されるものでも）、資格情報には `roles:write` も必要です。セットから特権ロールを削除する場合は `users:write` のみで足ります。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `user_id` | path | はい | ユーザー ID（`usr_…`）。 |
| `role_ids` | string[] | はい | 環境ロール ID（`rol_…`）の完全なセット。最大 50 件。 |

## レスポンス

新しいロール ID を含む `200 OK`。

```json
{
  "role_ids": [
    "rol_01j9xr7s1t2w6x8y0z2a4b6c8e"
  ]
}
```

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 403 | `role_not_assignable` | ロールが組織ロールである。 |
| 404 | `not_found` | この環境にユーザーが存在しない。 |
| 422 | `validation_failed` | `role_ids` が欠落している、形式が不正または未知の ID（`unknown_role`）を含む、重複がある、または 50 件を超えている。 |
| 401 | `unauthenticated` | 資格情報が欠落している、無効、または取り消されている。 |
| 403 | `insufficient_permissions` | 資格情報に必要な権限がない。特権ロール（`is_privileged`）を割り当てるには `roles:write` も必要。これがない場合は何も書き込まれず、`required_permissions` に両方の権限が表示される。 |
| 429 | `rate_limited` | レート制限を超えた。`Retry-After` の期間後に再試行する。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できない。`Retry-After` の期間後に再試行する。 |

## 例

```bash
curl -i -X PUT "https://api.eu.keenauth.com/v1/users/usr_01j9xh2k6p7q1r3s5t7v9w1x3y/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e"]}'
```