사용자 관리

이 페이지에서는 Admin API를 사용하여 Claude Enterprise(claude.ai) 조직의 구성원을 프로그래밍 방식으로 관리하는 방법을 다룹니다: 구성원 목록을 조회하고 이메일 주소로 검색하기, 구성원의 역할 변경하기, 구성원 제거하기, 초대 발송 및 철회하기, 엔터프라이즈의 그룹과 그 구성원 관리하기, 조직의 사용자 지정 역할 조회하기. Claude Console(Claude Platform) 조직의 경우 Claude Console용 Admin API 가이드를 참조하세요.

조직에서 사용할 수 있는 엔드포인트는 무엇인가요?

Admin API는 https://api.anthropic.com/v1/organizations/ 아래의 단일 엔드포인트 집합입니다. Claude Console 조직과 Claude Enterprise 조직은 서로 다른 키로 인증하며, 각각 엔드포인트의 서로 다른 하위 집합에 접근할 수 있습니다:

구성원 및 초대 엔드포인트는 두 조직 유형 모두에서 동일하며, 이 페이지에서는 Claude Enterprise 조직 역할을 포함하여 Claude Enterprise에서의 동작을 설명합니다. 그룹 및 사용자 지정 역할 엔드포인트는 Claude Enterprise에만 존재합니다.

개요

이 페이지에서는 다섯 가지 리소스를 다룹니다:

사용자 지정 역할과 그룹 연결은 claude.ai 조직 설정에서 관리되며, API는 이를 읽을 수는 있지만 변경할 수는 없습니다.

빠른 시작

ANTHROPIC_API_KEY 환경 변수를 Admin API 키로 설정하세요. 이 페이지의 예제는 이 변수에서 키를 읽습니다. SDK와 ant CLI는 Authorization 및 anthropic-version 헤더를 자동으로 전송합니다.

조직의 구성원 목록을 최신순으로 조회합니다:

client = anthropic.Anthropic()

users = client.organization.users.list(limit=20)

for user in users:
    print(f"{user.id}: {user.email} ({user.role})")

{
  "data": [
    {
      "type": "user",
      "id": "user_01AbCdEfGhIjKlMnOpQrSt",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "user",
      "added_at": "2026-06-12T09:14:03Z"
    }
  ],
  "has_more": false,
  "first_id": "user_01AbCdEfGhIjKlMnOpQrSt",
  "last_id": "user_01AbCdEfGhIjKlMnOpQrSt"
}

핵심 개념

조직 역할

모든 구성원은 정확히 하나의 조직 역할을 가집니다. 조회 시 구성원의 역할은 다섯 가지 값 중 하나로 반환됩니다:

API는 초대 생성 및 역할 업데이트 시 user 및 managed 역할만 할당할 수 있습니다. managed 구성원의 권한은 소속 그룹에 연결된 사용자 지정 역할에서 비롯되므로, managed를 할당하려면 write:members에 더해 write:rbac_groups 범위가 필요합니다. 관리 역할(owner, membership_admin, primary_owner)은 claude.ai 조직 설정에서 할당되며, 이러한 역할을 가진 구성원은 이 API를 통해 수정하거나 제거할 수 없습니다.

구성원과 초대

사람은 초대를 수락하여(또는 구성된 경우 조직의 싱글 사인온을 통해) 구성원이 됩니다. 초대를 생성하면 초대 이메일이 발송되며, 이후 초대는 수신자가 수락하거나(accepted) 서버가 할당한 expires_at이 지날 때까지(expired) pending 상태로 조회됩니다. pending 상태의 초대만 철회할 수 있습니다. 대기 중인 초대의 이메일 주소나 역할을 변경하려면 초대를 철회하고 새로 생성하세요.

조직의 플랜이 구매한 유한한 좌석 풀에서 구성원을 할당하는 경우, 대기 중인 초대는 좌석을 하나 차지합니다. 초대 생성 엔드포인트는 좌석이나 등급 매개변수를 받지 않으며, 좌석은 여유가 있는 가장 낮은 등급에서 자동으로 할당됩니다. 빈 좌석이 없을 때 초대를 생성하면 좌석을 구매하는 대신 400 오류로 실패합니다. 초대를 철회하거나, 만료되도록 두거나, 나중에 구성원을 제거하면 좌석이 풀로 반환됩니다.

그룹과 역할

그룹은 구성원을 사용자 지정 역할에 연결합니다("role-based access control"(역할 기반 접근 제어), 엔드포인트 경로와 범위 이름의 rbac). 그룹은 단일 조직이 아닌 엔터프라이즈 전체(상위 조직과 그 아래의 모든 조직)가 소유하므로, 그룹 범위(read:rbac_groups 및 write:rbac_groups)에는 연결된 모든 조직에 대해 생성된 키가 필요합니다. 각 그룹에는 source_type이 있습니다: claude.ai에서 생성된 그룹은 direct, ID 공급자가 프로비저닝한 그룹은 scim입니다. 그룹의 role_ids 필드는 그룹에 연결된 사용자 지정 역할의 ID를 나열합니다. 사용자 지정 역할 엔드포인트로 이를 이름과 권한으로 확인할 수 있는데, 역할 카탈로그는 조직별이고 그룹은 엔터프라이즈 전체 단위이므로 엔터프라이즈의 다른 조직에 속한 역할을 가져오면 해당 키에 대해 404가 반환된다는 점에 유의하세요. 역할 데이터를 일시적으로 사용할 수 없는 경우 이 필드는 ([]가 아닌) null이므로, 재시도하여 성능이 저하된 조회와 역할이 없는 그룹을 구분하세요.

버전 관리

모든 요청에 anthropic-version 헤더를 보내세요. 사용 가능한 버전은 API 버전을 참조하세요.

속도 제한

Admin API 엔드포인트는 조직당 분당 100개 요청의 제한을 공유하며, 초대 생성에는 대신 시간당 1,200개 요청이라는 별도의 제한이 적용됩니다. 제한을 초과한 요청은 429 Too Many Requests를 반환합니다.

페이지네이션

구성원 및 초대 목록은 ID 기반 페이지네이션을 사용합니다: limit(기본값 20, 최대 1000)과 함께 before_id 또는 after_id 중 최대 하나를 전달하고, has_more가 false가 될 때까지 각 응답의 first_id 및 last_id 필드를 사용하여 페이지를 넘기세요. 그룹 및 사용자 지정 역할 목록은 대신 불투명 커서를 사용합니다: next_page가 null이 될 때까지 응답의 next_page 값을 다음 요청의 page 매개변수로 그대로 전달하세요.

결과를 반복 처리할 때 SDK가 추가 페이지를 자동으로 가져오므로, limit은 전체 개수가 아닌 페이지 크기를 설정합니다. CLI에서 --limit은 구성원 및 초대 목록의 경우 전체 결과 수를 설정합니다. 그룹 및 역할 목록의 경우에는 페이지 크기를 설정합니다.

오류 응답

오류 응답은 오류에 설명된 표준 형식을 따릅니다.

구성원

구성원 목록 조회

GET /v1/organizations/users는 조직의 구성원을 가장 최근에 추가된 순서로 반환합니다. 특정 구성원을 찾으려면 email로 필터링하세요. 일치 여부는 대소문자를 구분하지 않으며 동일한 주소의 일반적인 변형을 허용합니다(예: jane+hiring@example.com은 jane@example.com과 일치합니다). read:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 List users를 참조하세요.

client = anthropic.Anthropic()

users = client.organization.users.list(email="jane@example.com")

for user in users:
    print(f"{user.id}: {user.email} ({user.role})")

구성원 조회

GET /v1/organizations/users/{user_id}는 ID로 구성원 한 명을 반환합니다. read:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Get user를 참조하세요.

client = anthropic.Anthropic()

user = client.organization.users.retrieve("user_01AbCdEfGhIjKlMnOpQrSt")

print(f"id: {user.id}")
print(f"email: {user.email}")
print(f"role: {user.role}")

구성원의 역할 변경

POST /v1/organizations/users/{user_id}는 구성원의 역할을 user 또는 managed로 설정합니다. 관리 역할(owner, membership_admin 또는 primary_owner)을 가진 구성원은 이 엔드포인트로 변경할 수 없으며, 관리 역할을 할당할 수도 없습니다. 두 경우 모두 400을 반환하며 claude.ai 조직 설정에서 관리됩니다. 조직의 ID 공급자가 역할을 관리하는 경우(고급 SSO 또는 고급 SCIM 프로비저닝), 역할 업데이트는 400을 반환합니다. write:members 범위가 필요하며, 역할을 managed로 변경할 때는 write:rbac_groups도 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Update user를 참조하세요.

client = anthropic.Anthropic()

user = client.organization.users.update("user_01AbCdEfGhIjKlMnOpQrSt", role="managed")

print(f"id: {user.id}")
print(f"role: {user.role}")

구성원 제거

DELETE /v1/organizations/users/{user_id}는 조직에서 구성원을 제거하고, 해당 구성원이 차지하던 구매 좌석을 조직의 풀로 반환합니다. 관리 역할을 가진 구성원은 이 엔드포인트로 제거할 수 없으며, ID 공급자가 구성원 자격을 관리하는 경우(SCIM) 제거 요청은 400을 반환합니다. write:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Remove user를 참조하세요.

client = anthropic.Anthropic()

removed_user = client.organization.users.remove("user_01AbCdEfGhIjKlMnOpQrSt")

print(f"id: {removed_user.id}")

{
  "type": "user_deleted",
  "id": "user_01AbCdEfGhIjKlMnOpQrSt"
}

초대

초대 생성

POST /v1/organizations/invites는 초대 이메일을 발송하고 서버가 할당한 expires_at과 함께 초대를 반환합니다. role은 user 또는 managed여야 합니다. 해당 이메일 주소에 대한 대기 중인 초대가 이미 있거나 주소가 이미 구성원에 속한 경우, 요청은 기존 리소스를 명시하는 400을 반환합니다. ID 공급자가 사용자를 자동으로 프로비저닝하는 조직(JIT 또는 SCIM)은 API를 통해 초대를 생성할 수 없습니다. write:members 범위가 필요하며, role이 managed인 경우 write:rbac_groups도 필요합니다.

유한한 좌석 풀에서 구성원을 할당하는 플랜에서는 초대가 여유가 있는 가장 낮은 등급에서 자동으로 좌석을 가져옵니다. API는 등급 매개변수를 받지 않습니다. 빈 좌석이 없으면 요청은 좌석을 구매하는 대신 400 오류로 실패합니다. 조직의 플랜 관리에서 좌석을 추가한 후 다시 시도하세요.

선택적 rbac_group_ids 필드는 구성원이 초대를 수락할 때 할당할 그룹을 (rbac_group_ 접두사가 붙은 ID로) 나열합니다. 그룹 할당은 그룹의 역할에 연결된 권한을 부여할 수 있으므로, 비어 있지 않은 rbac_group_ids를 전달하려면 키에 write:rbac_groups 범위도 있어야 합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Create invite를 참조하세요.

client = anthropic.Anthropic()

invite = client.organization.invites.create(
    email="newhire@example.com",
    role="managed",
    rbac_group_ids=["rbac_group_01UvWxYzAbCdEfGhIjKlMn"],
)

print(f"id: {invite.id}")
print(f"email: {invite.email}")
print(f"status: {invite.status}")
print(f"expires_at: {invite.expires_at}")

{
  "type": "invite",
  "id": "invite_01QrStUvWxYzAbCdEfGhIj",
  "email": "newhire@example.com",
  "role": "managed",
  "invited_at": "2026-07-06T16:20:11Z",
  "expires_at": "2026-07-27T16:20:11Z",
  "accepted_at": null,
  "status": "pending",
  "rbac_group_ids": ["rbac_group_01UvWxYzAbCdEfGhIjKlMn"]
}

초대 목록 조회

GET /v1/organizations/invites는 pending, accepted, expired 상태 전체에 걸쳐 조직의 초대를 최신순으로 반환합니다. 상태 필터는 없습니다. read:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 List invites를 참조하세요.

client = anthropic.Anthropic()

invites = client.organization.invites.list(limit=20)

for invite in invites:
    print(f"{invite.id}: {invite.email} ({invite.status})")

초대 조회

GET /v1/organizations/invites/{invite_id}는 ID로 초대 하나를 반환합니다. read:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Get invite를 참조하세요.

client = anthropic.Anthropic()

invite = client.organization.invites.retrieve("invite_01QrStUvWxYzAbCdEfGhIj")

print(f"id: {invite.id}")
print(f"email: {invite.email}")
print(f"status: {invite.status}")

초대 철회

DELETE /v1/organizations/invites/{invite_id}는 pending 상태의 초대를 철회하여 초대 이메일의 링크를 비활성화합니다. accepted 상태의 초대를 철회하면 400이 반환되며(대신 구성원을 제거하세요), expired 상태의 초대를 철회해도 400이 반환됩니다. write:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Delete invite를 참조하세요.

client = anthropic.Anthropic()

deleted_invite = client.organization.invites.delete("invite_01QrStUvWxYzAbCdEfGhIj")

print(f"id: {deleted_invite.id}")

그룹

엔터프라이즈가 claude.ai 조직 설정에서 또는 이 API를 통해 직접 생성한 그룹(source_type: "direct")은 이 섹션의 모든 엔드포인트를 지원합니다. ID 공급자가 프로비저닝한 그룹(source_type: "scim")은 조회할 수 있지만 수정할 수는 없습니다. SCIM 그룹은 ID 공급자가 소유하므로, 이름을 변경하거나 삭제하거나 구성원을 변경하면 400이 반환됩니다.

그룹 목록 조회

GET /v1/organizations/rbac_groups는 ID 공급자가 관리하는(scim) 그룹을 포함하여 엔터프라이즈의 그룹을 반환합니다. read:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 List groups를 참조하세요.

client = anthropic.Anthropic()

groups = client.beta.organization.rbac_groups.list(limit=20)

for group in groups:
    print(f"{group.id}: {group.name} ({group.source_type})")

{
  "data": [
    {
      "type": "rbac_group",
      "id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
      "name": "Engineering",
      "source_type": "direct",
      "role_ids": ["rbac_role_01CdEfGhIjKlMnOpQrStUv"],
      "roles": ["rbac_role_01CdEfGhIjKlMnOpQrStUv"],
      "created_at": "2026-03-18T10:01:42Z",
      "updated_at": "2026-05-02T08:55:09Z"
    }
  ],
  "has_more": false,
  "next_page": null
}

그룹 조회

GET /v1/organizations/rbac_groups/{rbac_group_id}는 ID로 그룹 하나를 반환합니다. read:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Get group을 참조하세요.

client = anthropic.Anthropic()

group = client.beta.organization.rbac_groups.retrieve(
    "rbac_group_01UvWxYzAbCdEfGhIjKlMn"
)

print(f"id: {group.id}")
print(f"name: {group.name}")
print(f"source_type: {group.source_type}")

그룹 생성

POST /v1/organizations/rbac_groups는 지정된 name(1–255자)으로 역할이나 구성원이 없는 그룹을 생성합니다. write:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Create group을 참조하세요.

client = anthropic.Anthropic()

group = client.beta.organization.rbac_groups.create(name="Engineering")

print(f"id: {group.id}")
print(f"name: {group.name}")

{
  "type": "rbac_group",
  "id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
  "name": "Engineering",
  "source_type": "direct",
  "role_ids": [],
  "roles": [],
  "created_at": "2026-07-09T18:00:00Z",
  "updated_at": "2026-07-09T18:00:00Z"
}

그룹 이름 변경

POST /v1/organizations/rbac_groups/{rbac_group_id}는 그룹을 업데이트합니다. 이 엔드포인트로 변경할 수 있는 필드는 name뿐입니다. write:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Update group을 참조하세요.

client = anthropic.Anthropic()

group = client.beta.organization.rbac_groups.update(
    "rbac_group_01UvWxYzAbCdEfGhIjKlMn", name="Platform Engineering"
)

print(f"id: {group.id}")
print(f"name: {group.name}")

그룹 삭제

DELETE /v1/organizations/rbac_groups/{rbac_group_id}는 그룹을 삭제합니다. 그룹의 구성원은 소속 조직의 구성원으로 남지만, 그룹에 연결된 역할의 권한을 잃게 되며, 그룹 지출 한도가 있었다면 더 이상 적용되지 않습니다. write:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Delete group을 참조하세요.

client = anthropic.Anthropic()

deleted_group = client.beta.organization.rbac_groups.delete(
    "rbac_group_01UvWxYzAbCdEfGhIjKlMn"
)

print(f"id: {deleted_group.id}")

{
  "id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
  "type": "rbac_group_deleted"
}

그룹 구성원 목록 조회

GET /v1/organizations/rbac_groups/{rbac_group_id}/members는 그룹의 구성원(각각 user_id 및 이메일 포함)을 오래된 순서로 반환합니다. 엔터프라이즈 조직의 현재 구성원만 반환되므로, has_more가 true인 상태에서도 페이지에 limit보다 적은 항목이 포함될 수 있습니다. read:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 List group members를 참조하세요.

client = anthropic.Anthropic()

members = client.beta.organization.rbac_groups.members.list(
    "rbac_group_01UvWxYzAbCdEfGhIjKlMn", limit=100
)

for member in members:
    print(f"{member.user_id}: {member.email}")

{
  "data": [
    {
      "type": "rbac_group_member",
      "rbac_group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
      "group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
      "user_id": "user_01AbCdEfGhIjKlMnOpQrSt",
      "email": "jane@example.com",
      "created_at": "2026-04-07T12:30:00Z"
    }
  ],
  "has_more": false,
  "next_page": null
}

그룹에 구성원 추가

POST /v1/organizations/rbac_groups/{rbac_group_id}/members는 user_id로 조직 구성원을 그룹에 추가합니다. 사용자는 이미 엔터프라이즈 조직 중 하나의 구성원이어야 하며(그렇지 않으면 요청이 404를 반환합니다), 이미 그룹에 있는 사람을 추가하면 400이 반환됩니다. scim 그룹의 경우 구성원 자격은 ID 공급자에서 관리되며 이 요청은 400을 반환합니다. 아직 가입하지 않은 사람에게 그룹을 할당하려면 대신 초대 생성 시 rbac_group_ids를 사용하세요. write:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Add group member를 참조하세요.

client = anthropic.Anthropic()

member = client.beta.organization.rbac_groups.members.add(
    "rbac_group_01UvWxYzAbCdEfGhIjKlMn", user_id="user_01AbCdEfGhIjKlMnOpQrSt"
)

print(f"user_id: {member.user_id}")
print(f"email: {member.email}")

{
  "type": "rbac_group_member",
  "rbac_group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
  "group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
  "user_id": "user_01AbCdEfGhIjKlMnOpQrSt",
  "email": "jane@example.com",
  "created_at": "2026-07-09T18:00:00Z"
}

그룹에서 구성원 제거

DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}는 그룹에서 구성원을 제거하며, 해당 구성원은 소속 조직의 구성원으로 남습니다. 사용자가 그룹의 구성원이 아니면 요청은 404를 반환하고, 구성원 자격이 ID 공급자에서 관리되는 scim 그룹의 경우 400을 반환합니다. write:rbac_groups 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Remove group member를 참조하세요.

client = anthropic.Anthropic()

removed_member = client.beta.organization.rbac_groups.members.remove(
    "user_01AbCdEfGhIjKlMnOpQrSt", rbac_group_id="rbac_group_01UvWxYzAbCdEfGhIjKlMn"
)

print(f"user_id: {removed_member.user_id}")

{
  "rbac_group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
  "group_id": "rbac_group_01UvWxYzAbCdEfGhIjKlMn",
  "user_id": "user_01AbCdEfGhIjKlMnOpQrSt",
  "type": "rbac_group_member_deleted"
}

사용자 지정 역할

사용자 지정 역할은 API를 통해 읽기 전용으로만 사용할 수 있습니다: 이 엔드포인트는 조직의 사용자 지정 역할(claude.ai 조직 설정에서 정의되었거나 Anthropic이 프로비저닝한 역할)과 각 역할이 부여하는 권한을 카탈로그로 제공합니다. 사용자 지정 역할 조회는 read:members 범위를 사용하며(별도의 역할 범위는 없음) 조직 수준 키로 작동합니다. 그룹 엔드포인트와 달리 연결된 모든 조직에 대해 생성된 키가 필요하지 않으며, 반환되는 카탈로그는 해당 조직 자체의 것입니다.

역할의 이름은 display_name 필드에서 읽으세요. Anthropic이 프로비저닝한 역할의 경우 display_name이 claude.ai에 표시되는 레이블과 다를 수 있으며, Anthropic이 이름을 변경할 수도 있습니다. 역할에 대한 지속적인 참조를 유지하려면 해당 역할의 id를 저장하세요.

역할 목록 조회

GET /v1/organizations/rbac_roles는 조직의 사용자 지정 역할을 반환합니다. read:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 List roles를 참조하세요.

client = anthropic.Anthropic()

roles = client.beta.organization.rbac_roles.list(limit=20)

for role in roles:
    print(f"{role.id}: {role.display_name}")

{
  "data": [
    {
      "type": "rbac_role",
      "id": "rbac_role_01CdEfGhIjKlMnOpQrStUv",
      "display_name": "Engineering base",
      "name": "Engineering base",
      "created_at": "2026-03-18T10:01:42Z",
      "updated_at": "2026-05-02T08:55:09Z"
    }
  ],
  "has_more": false,
  "next_page": null
}

역할 조회

GET /v1/organizations/rbac_roles/{rbac_role_id}는 ID로 역할 하나를 반환합니다. read:members 범위가 필요합니다.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 Get role을 참조하세요.

client = anthropic.Anthropic()

role = client.beta.organization.rbac_roles.retrieve("rbac_role_01CdEfGhIjKlMnOpQrStUv")

print(f"id: {role.id}")
print(f"display_name: {role.display_name}")

역할의 권한 목록 조회

GET /v1/organizations/rbac_roles/{rbac_role_id}/permissions는 역할의 권한을 반환합니다. 각 권한은 resource(적용 대상: 조직의 제품 기능, 커넥터 도구, 커넥터 OAuth 범위, 하나의 커넥터 또는 모든 커넥터)와 action(해당 리소스에 대해 부여하는 것)의 쌍으로 구성됩니다. 조직에서 활성화되지 않은 기능에 대한 행은 생략되므로, has_more가 true인 상태에서도 페이지에 limit보다 적은 행이 포함될 수 있습니다. read:members 범위가 필요합니다.

두 가지 action 값은 특별히 주의해야 합니다: action이 capability_access_all(모든 제품 기능) 또는 capability_access_all_ga(모든 안정적인 제품 기능, 즉 베타 또는 연구 프리뷰로 표시되지 않은 모든 기능)인 organization 권한은 포괄적 부여(모델 접근이나 permission_ 접두사가 붙은 관리자 패널 권한은 포함하지 않음)이며, 확장되지 않고 해당 단일 행으로 나열됩니다. 역할이 부여하는 권한을 집계할 때는 포괄적 행이 다른 행에 명시된 기능뿐만 아니라 해당 변형이 설명하는 모든 것을 포함하는 것으로 취급하세요.

전체 매개변수 세부 정보와 응답 스키마는 API 레퍼런스의 List role permissions를 참조하세요.

client = anthropic.Anthropic()

permissions = client.beta.organization.rbac_roles.permissions.list(
    "rbac_role_01CdEfGhIjKlMnOpQrStUv", limit=20
)

for permission in permissions:
    print(permission.action)

{
  "data": [
    {
      "type": "rbac_role_permission",
      "resource": {
        "type": "organization",
        "organization_id": "12345678-1234-5678-1234-567812345678"
      },
      "action": "capability_access_all_ga"
    },
    {
      "type": "rbac_role_permission",
      "resource": {
        "type": "connector_tool",
        "connector_id": "mcpsrv_01WxYzAbCdEfGhIjKlMnOp",
        "tool_name": "search_tickets"
      },
      "action": "use"
    }
  ],
  "has_more": false,
  "next_page": null
}

예제 워크플로

퇴사하는 직원 오프보딩

1. 이메일로 구성원을 검색합니다:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client = anthropic.Anthropic()
   
   users = client.organization.users.list(email="departing@example.com")
   
   for user in users:
       print(f"{user.id}: {user.email} ({user.role})")

2. 응답의 id를 사용하여 DELETE /v1/organizations/users/{user_id}로 해당 구성원을 제거합니다. 좌석이 있었다면 풀로 반환됩니다.

3. 해당 사람이 아직 가입하지 않았다면 검색 결과에 구성원이 반환되지 않습니다. 대신 초대 목록을 조회하고 해당 pending 초대를 철회하세요.

그룹 구성원 감사

1. 그룹 목록을 조회하고 각 그룹의 id, name, role_ids를 기록합니다.

2. 민감한 역할을 가진 각 그룹에 대해 GET /v1/organizations/rbac_groups/{rbac_group_id}/members의 페이지를 넘기며 구성원 이메일을 ID 공급자의 명단과 비교합니다.

3. 더 이상 그룹에 있어서는 안 되는 구성원을 DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}로 제거합니다. scim 그룹의 경우 대신 ID 공급자에서 변경하세요.

그룹 구성원 관리와 일시적인 지출 한도 상향을 결합한 워크플로는 Spend Limits API 페이지의 인시던트 중 구성원의 지출 한도 일시적으로 상향하기를 참조하세요.

자주 묻는 질문

이것은 Admin API와 다른 API인가요?

아니요. 구성원 및 초대 엔드포인트는 Claude Console 조직이 사용하는 것과 동일한 /v1/organizations/ 엔드포인트이며, 이 페이지에서는 Claude Enterprise에서의 동작을 설명합니다. 그룹 및 사용자 지정 역할 엔드포인트는 동일한 API의 일부이며 Claude Enterprise 조직에만 존재합니다. 사용 가능 여부 표에서 각 조직 유형이 호출할 수 있는 엔드포인트를 확인할 수 있습니다.

API를 통해 소유자 또는 구성원 관리자 역할을 할당할 수 있나요?

아니요. API는 초대 생성 및 역할 업데이트 시 user와 managed만 할당합니다. 관리 역할은 claude.ai 조직 설정에서 할당되며, 이러한 역할을 가진 구성원은 API를 통해 수정하거나 제거할 수 없습니다.

API를 통해 그룹을 생성하거나 수정할 수 있나요?

예, write:rbac_groups 범위가 있으면 그룹을 생성, 이름 변경, 삭제하고 구성원을 추가하거나 제거할 수 있습니다. API가 변경할 수 없는 것은 두 가지입니다: 이름과 구성원 자격을 ID 공급자가 소유하는, ID 공급자가 프로비저닝한 그룹(source_type: "scim")과, claude.ai 조직 설정에서 관리되는 사용자 지정 역할입니다(API는 이를 읽을 수 있습니다).

수락되지 않은 초대도 좌석을 차지하나요?

유한한 좌석 풀이 있는 플랜에서는 그렇습니다: pending 상태의 초대는 좌석을 하나 차지합니다. 초대를 철회하거나 만료되도록 두면 좌석이 해제됩니다. 좌석 풀이 없는 플랜에서는 초대가 아무것도 차지하지 않습니다.

조직에서 싱글 사인온을 사용합니다. 어떤 작업이 가능한가요?

ID 공급자가 사용자를 자동으로 프로비저닝하는 경우(JIT 또는 SCIM), 초대 생성은 400을 반환합니다. 역할을 관리하는 경우(고급 SSO 또는 고급 SCIM 프로비저닝), 역할 업데이트는 400을 반환합니다. 구성원 자격을 관리하는 경우(SCIM 프로비저닝), 구성원 제거는 400을 반환합니다. 조회는 어떤 경우에도 작동합니다.

Admin API 키를 생성한 사람이 퇴사하면 키는 어떻게 되나요?

키는 계속 작동합니다. Admin API 키는 개별 사용자가 아닌 조직 범위로 지정되며, claude.ai에서 생성된 키는 만료되지 않습니다. 생성자를 조직에서 제거하거나 ID 공급자를 통해 프로비저닝을 해제하면 해당 사람 본인의 접근은 종료되지만, 그 사람이 생성한 키는 종료되지 않습니다. 역할을 하향 조정해도 키는 변경되지 않으며, 각 키는 원래 범위로 활성 상태를 유지합니다. Admin API 키를 생성한 사람을 오프보딩할 때는 claude.ai > 조직 설정 > API의 Keys 섹션에서 해당 키를 삭제하고 대체 키를 생성하세요.

참고 항목