# 역할 권한 설정

`PUT /fapi/v1/organizations/{org_id}/roles/{role_id}/permissions` · 환경의 로그인 호스트에서 호출

조직 역할의 권한 집합을 교체합니다. 환경이 조직 역할에 허용한 권한만 사용할 수 있으며, 관리자는 자신이 보유한 권한만 부여할 수 있습니다. 여기에서는 권한이나 API를 생성할 수 없습니다. 인증된 사용자의 `__Host-idp_session` 쿠키가 필요하며, 쿠키가 없거나 만료되었거나 취소된 경우 `401 unauthenticated`를 반환합니다. 다른 origin의 자사 애플리케이션은 대신 프론트 API 액세스 토큰(DPoP 증명과 함께 `Authorization: DPoP <token>`)을 보낼 수 있습니다([프론트 API 액세스 토큰](/docs/api/fapi/front-api-token) 참조). 사용자는 `idp_roles:manage` 권한을 가진 조직의 활성 멤버여야 합니다. 멤버가 아닌 사용자는 `404 not_found`를 받으며, 이로써 조직의 존재 여부가 노출되지 않습니다. 권한이 없는 멤버는 `403 insufficient_permissions`를 받습니다. 조직 역할은 환경에서 활성화되어 있고 요금제에 포함되어 있어야 합니다.

## 요청

헤더:

| 헤더 | 필수 여부 | 설명 |
| --- | --- | --- |
| `Idp-Client` | 예 | SDK 식별자. |
| `Origin` | 예 | 정확히 `https://<sign-in host>`여야 합니다. |
| `Content-Type` | 본문이 있는 경우 | `application/json`. |
| `If-Match` | 아니요 | 마지막으로 읽은 역할의 `"<version>"`. 그 이후 역할이 변경되었다면 `412 precondition_failed`를 반환하며 아무것도 변경되지 않습니다. |

`org_id`: 조직 식별자(`org_…`). `role_id`: 역할 식별자(`rol_…`).

본문:

| 필드 | 필수 여부 | 설명 |
| --- | --- | --- |
| `permission_ids` | 예 | 전체 집합이며, 권한 식별자(`perm_…`)는 최대 100개입니다. `[]`를 보내면 모든 권한을 제거합니다. |

## 응답

새 `ETag`와 함께 `200 OK`를 반환하며, 본문은 역할입니다([조직 역할 조회](./get) 참조).

## 오류

| 상태 | 코드 | 발생 조건 |
| --- | --- | --- |
| 401 | `unauthenticated` | 유효한 세션 쿠키가 없습니다. |
| 403 | `origin_not_allowed` | `Origin`이 없거나 잘못되었습니다. |
| 403 | `insufficient_permissions` | 사용자에게 조직의 `idp_roles:manage` 권한이 없습니다. |
| 403 | `plan_feature_unavailable` | 환경의 요금제에 조직 역할이 포함되어 있지 않습니다(`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | 환경에서 조직 역할이 꺼져 있습니다. |
| 403 | `role_not_assignable` | 역할 또는 새 집합이 사용자가 보유하지 않은 권한을 부여하거나, 사용자 본인의 멤버십에 해당 역할이 포함되어 있습니다. |
| 404 | `not_found` | 이 사용자에 대한 조직 또는 조직 역할이 없습니다. 환경 역할, 알 수 없거나 형식이 잘못되었거나 다른 사용자의 식별자도 같은 응답을 받습니다. |
| 409 | `organization_pending_deletion` | 조직이 삭제 예정입니다. |
| 412 | `precondition_failed` | `If-Match`가 현재 버전을 가리키지 않거나, 요청을 처리하는 동안 역할이 변경되었습니다. |
| 422 | `permission_not_allowed` | 해당 권한은 조직 역할에 허용되지 않습니다. |
| 422 | `permission_reserved` | 해당 권한은 플랫폼용으로 예약되어 있습니다. |
| 422 | `validation_failed` | 목록이 잘못되었거나 너무 깁니다. |
| 503 | `service_unavailable` | 일시적으로 사용할 수 없습니다. `Retry-After` 이후에 다시 시도하십시오. |

## 예제

```bash
curl -X PUT https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w/permissions \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"permission_ids":["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"]}'
```