멤버십의 역할 교체

PUT /v1/organizations/{org_id}/memberships/{membership_id}/roles · 권한 organizations:write

멤버십에 수동으로 할당된 역할을 role_ids로 교체합니다(빈 배열이면 모든 역할을 제거합니다). IdP 매핑이나 디렉터리 소스로 부여된 역할은 변경되지 않습니다. role_version을 지정하는 경우 멤버십의 현재 version과 일치해야 하며, 일치하지 않으면 409 conflict가 반환됩니다. 마지막 관리자의 관리자 역할은 제거할 수 없습니다. 이 쓰기 작업은 organization_membership.updated로 감사 기록됩니다.

요청

필드 유형 필수 설명
org_id path 예 조직 ID(org_…)입니다.
membership_id path 예 멤버십 ID(mem_…)입니다.
role_ids string[] 예 전체 역할 ID(rol_…) 집합이며, 최대 50개입니다.
role_version integer 아니요 예상되는 멤버십 version(1 이상)입니다.
revoke_sessions boolean 아니요 기본값은 true입니다. 특권 역할(is_privileged)을 제거할 때 이 조직 컨텍스트에서 사용자의 리프레시 토큰 패밀리를 취소할지 선택합니다(계획 §17.4). false로 설정하면 취소하지 않습니다. 이번 릴리스에서는 이 선택이 organization_membership.updated 감사 기록의 revoke_sessions 메타데이터에만 기록되며 세션은 취소되지 않습니다. 취소는 인증 서비스에서 예정(planned)되어 있습니다.

응답

200 OK와 함께 업데이트된 멤버십 및 해당 ETag를 반환합니다.

{
  "id": "mem_01j9xn5p9s0t4v6w8x0y2z4a6c",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "user_id": "usr_01j9xh2k6p7q1r3s5t7v9w1x3y",
  "status": "active",
  "source": "admin_api",
  "reason": null,
  "roles": [
    {
      "role_id": "rol_01j9xr7s1t2w6x8y0z2a4b6c8e",
      "source": "admin_api",
      "assigned_at": "2026-10-12T09:31:00.123456Z"
    }
  ],
  "expires_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "activated_at": "2026-10-12T09:31:00.123456Z",
  "suspended_at": null,
  "removed_at": null,
  "updated_at": "2026-10-12T09:31:00.123456Z",
  "version": 2
}

오류

HTTP code 발생 조건
404 not_found 이 조직에 멤버십이 존재하지 않습니다.
403 role_not_assignable 역할이 환경 역할이거나 이 조직의 역할이 아닙니다.
409 conflict role_version이 멤버십의 현재 버전과 일치하지 않습니다.
409 last_org_admin 이 변경으로 조직에 활성 관리자가 남지 않습니다.
422 validation_failed role_ids가 없거나 잘못되었거나, role_version이 1보다 작습니다.
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/organizations/org_01j9xk3m7q8r2s4t6v8w0y2z4a/memberships/mem_01j9xn5p9s0t4v6w8x0y2z4a6c/roles" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_ids":["rol_01j9xr7s1t2w6x8y0z2a4b6c8e","rol_01j9xs8t2v3x7y9z1a3b5c7d9f"],"role_version":1}'

개인정보

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