역할 권한 설정

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

조직 역할의 권한 집합을 교체합니다. 환경이 조직 역할에 허용한 권한만 사용할 수 있으며, 관리자는 자신이 보유한 권한만 부여할 수 있습니다. 여기에서는 권한이나 API를 생성할 수 없습니다. 인증된 사용자의 __Host-idp_session 쿠키가 필요하며, 쿠키가 없거나 만료되었거나 취소된 경우 401 unauthenticated를 반환합니다. 다른 origin의 자사 애플리케이션은 대신 프론트 API 액세스 토큰(DPoP 증명과 함께 Authorization: DPoP <token>)을 보낼 수 있습니다(프론트 API 액세스 토큰 참조). 사용자는 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를 반환하며, 본문은 역할입니다(조직 역할 조회 참조).

오류

상태 코드 발생 조건
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 이후에 다시 시도하십시오.

예제

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