# 사용자의 직접 역할 교체

`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"]}'
```