멤버의 역할 설정

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

조직 프로필 화면에서 사용할 수 있도록, 멤버십의 역할을 전체 집합으로 교체합니다. 이 집합에는 현재 조직에서 볼 수 있는 역할만 포함됩니다. 즉 조직 자체의 역할과 조직 관리자에게 열려 있는 환경 역할입니다. 멤버의 나머지 역할은 그대로 유지됩니다. 빈 집합을 전달하면 볼 수 있는 모든 역할이 제거되며, 멤버에게 남은 역할이 없으면 조직의 기본 역할이 할당됩니다.

인증된 사용자의 __Host-idp_session 쿠키(정확한 Origin 포함) 또는 자사 앱의 프런트 API 액세스 토큰(DPoP 증명과 함께 Authorization: DPoP <token>; 프런트 API 액세스 토큰 참조)이 필요합니다. 사용자는 idp_members:update_roles 권한을 가진 조직의 활성 멤버여야 합니다. 멤버가 아닌 사용자는 404 not_found를 받고, 권한이 없는 멤버는 403 insufficient_permissions를 받습니다.

할당 규칙:

@keenauth/js 사용 시: await keenauth.organizations.setMemberRoles(orgId, membershipId, [roleId], { expectedVersion: 3 }).

요청

헤더:

헤더 필수 여부 설명
Idp-Client 예 SDK 식별자입니다.
Origin 예(쿠키 사용 시) https://<sign-in host>.
If-Match 아니요 멤버 목록에서 얻은 버전 하나, "<version>". 버전이 일치하지 않거나 두 개 이상이면 412 precondition_failed를 반환합니다.

org_id: 조직 식별자(org_…). membership_id: 멤버십 식별자(mem_…).

본문: {"role_ids": ["rol_…"]}, 최대 50개 역할. role_ids는 필수이며 []도 유효한 집합입니다.

응답

멤버십(멤버 목록의 항목과 같은 필드, 멤버 목록 참조)과 ETag: "<version>"를 포함한 200 OK.

오류

상태 코드 발생 조건
400 malformed_request If-Match 형식이 잘못되었습니다.
400 unknown_field 본문에 role_ids 외의 필드가 있습니다.
401 unauthenticated 유효한 세션 쿠키 또는 토큰이 없습니다.
403 insufficient_permissions 사용자에게 조직의 idp_members:update_roles 권한이 없습니다.
403 role_not_assignable 위의 할당 규칙 중 하나로 변경이 거부되었습니다.
403 origin_not_allowed Origin이 일치하지 않습니다.
404 not_found 이 사용자에게 해당 조직, 멤버십 또는 역할이 없습니다. 알 수 없거나, 형식이 잘못되었거나, 다른 사용자의 식별자도 같은 응답을 받습니다.
409 last_org_admin 변경 후 조직에 활성 관리자가 남지 않습니다.
409 role_limit_reached 멤버가 50개를 초과하는 역할을 보유하게 됩니다.
409 organization_disabled 조직이 비활성화되었거나 삭제 대기 중입니다(organization_pending_deletion).
412 precondition_failed If-Match가 멤버십의 현재 버전과 일치하지 않습니다.
422 validation_failed role_ids가 없거나, 너무 길거나, 형식이 잘못된 식별자를 포함합니다.
503 service_unavailable 일시적으로 사용할 수 없습니다. Retry-After 이후에 다시 시도하십시오.

예시

curl -X PUT "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/memberships/mem_01jbz6x8kq3m2n4p5r6s7t8v9b/roles" \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "3"' \
  -b cookies.txt \
  -d '{"role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"]}'

{
  "id": "mem_01jbz6x8kq3m2n4p5r6s7t8v9b",
  "user_id": "usr_01jbz6x8kq3m2n4p5r6s7t8v9c",
  "status": "active",
  "roles": [{ "role_id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w", "source": "admin_api" }],
  "created_at": "2026-11-03T09:00:00Z",
  "activated_at": "2026-11-03T09:00:00Z",
  "expires_at": null,
  "updated_at": "2026-11-03T10:00:00Z",
  "version": 4
}

개인 정보

이 엔드포인트는 개인 정보를 다룹니다: 조직 멤버십과 초대. KeenAuth API의 개인 정보에서 저장되는 항목, 보관 기간, 삭제 방법을 설명합니다. 어떤 필드에도 민감한 개인 정보(건강, 생체 정보, 종교, 정치적 견해, 성적 指向)를 보내지 마십시오.