사용자의 직접 역할 교체
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.
{
"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 기간 후에 다시 시도하십시오. |
예시
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"]}'