Admin API

Admin API를 사용하면 Claude Console에서 수동으로 관리하는 대신 조직의 멤버, 워크스페이스, 초대 및 API 키를 프로그래밍 방식으로 관리할 수 있습니다.

인증

세 가지 자격 증명 중 하나로 인증합니다. Admin API 키는 대부분의 엔드포인트를 지원합니다. 서비스 계정, 페더레이션 발급자 및 페더레이션 규칙 엔드포인트는 org:admin OAuth 토큰만 허용합니다. 개인 키 또는 서비스 계정 키는 Admin API 키와 마찬가지로 x-api-key 헤더로 전송하세요. 다음 예제는 OAuth 토큰과 Admin API 키로 조직 정보 엔드포인트를 호출합니다.

Python, TypeScript, C#, Go, Java, PHP 및 Ruby SDK는 client.beta.organization 아래에 Admin API를 노출하며, ant CLI는 ant beta:organization 아래에 노출합니다. 이 페이지의 예제는 기본 클라이언트를 사용하며, 이 클라이언트는 ANTHROPIC_API_KEY에서 Admin API 키를 읽거나 ANTHROPIC_AUTH_TOKEN에서 OAuth bearer 토큰을 읽습니다. Python, TypeScript, C#, Go 및 Java의 SDK 목록 메서드는 필요에 따라 추가 페이지를 가져오는 이터레이터를 반환하므로, limit은 전체 개수가 아니라 페이지 크기를 설정합니다. PHP, Ruby 및 curl 예제는 한 페이지를 반환합니다. CLI에서 --limit은 멤버, 초대, 워크스페이스, 워크스페이스 멤버 및 API 키 목록의 결과 수를 제한합니다. 각 엔드포인트의 매개변수와 응답은 Admin API 레퍼런스를 참조하세요.

OAuth bearer 토큰

org:admin 스코프를 가진 전용 프로필로 ant CLI에 로그인한 다음(관리자 액세스 참조), bearer 토큰을 export하세요. --profile admin은 org:admin 자격 증명을 자체 프로필에 저장하고 이를 CLI의 활성 프로필로 만듭니다. export된 변수는 해당 셸의 모든 SDK 및 CLI 호출에 적용됩니다. 관리 전용으로 사용하는 셸을 사용하고, 작업이 끝나면 변수를 unset한 뒤 ant profile activate default로 CLI를 다시 전환하세요:

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_AUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)

대화형 토큰은 수명이 짧습니다. 요청이 401을 반환하기 시작하면 export 명령을 다시 실행하여 토큰을 갱신하세요.

SDK와 ant CLI는 ANTHROPIC_AUTH_TOKEN을 자동으로 읽습니다. bearer 토큰을 전송하도록 같은 셸에서 ANTHROPIC_API_KEY는 설정하지 않은 상태로 두세요. 자동화된 워크로드는 로그인을 건너뜁니다. 워크로드 아이덴티티 페더레이션을 통해 인증하며, SDK와 CLI가 페더레이션 환경 변수로부터 토큰 교환을 수행합니다. WIF를 관리하도록 워크로드 부트스트랩하기를 참조하세요.

export된 토큰으로 Admin API를 호출하세요:

client = anthropic.Anthropic()

organization = client.beta.organization.retrieve()

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

org:admin 토큰은 기반이 되는 프로필이나 페더레이션 규칙이 바인딩된 워크스페이스와 관계없이 조직 전체에 대한 액세스 권한을 부여합니다.

CI 및 기타 비대화형 워크로드의 경우, 대화형으로 로그인하는 대신 Workload Identity Federation으로 토큰을 발급하세요. Admin API로 WIF 관리하기를 참조하세요.

Admin API 키

조직 유형에 맞는 Admin API 키를 생성하려면 Admin API 키 생성을 참조하세요.

client = anthropic.Anthropic()

organization = client.beta.organization.retrieve()

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

Admin API 작동 방식

인증의 자격 증명 중 하나로 인증한 다음, 다음 리소스를 관리합니다:

• 조직 멤버 및 역할
• 조직 초대
• 워크스페이스 및 워크스페이스 멤버
• API 키
• 서비스 계정, 페더레이션 발급자 및 페더레이션 규칙(org:admin OAuth 토큰 전용)

일반적인 용도로는 온보딩 및 오프보딩 자동화, 워크스페이스 액세스 관리, API 키 감사 등이 있습니다.

조직 역할 및 권한

조직 수준 역할은 다섯 가지가 있습니다. 자세한 내용은 API Console 역할 및 권한을 참조하세요.

조직 owner 및 primary owner는 모든 admin 권한을 가지며 admin도 관리할 수 있습니다. 이 페이지에서 admin 역할에 대한 모든 언급은 owner 및 primary owner에게도 적용됩니다.

주요 개념

조직 멤버

조직 멤버를 나열하고, 역할을 업데이트하고, 제거합니다.

조직의 멤버를 나열합니다:

client = anthropic.Anthropic()

users = client.beta.organization.users.list(limit=10)

# 필요에 따라 추가 페이지를 자동으로 가져옵니다.
for user in users:
    print(f"{user.id}: {user.email} ({user.role})")

멤버의 역할을 업데이트합니다:

client = anthropic.Anthropic()

user = client.beta.organization.users.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6", role="developer"
)

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

조직에서 멤버를 제거합니다:

client = anthropic.Anthropic()

removed_user = client.beta.organization.users.remove("user_01XyDMpzjS89pFZXqSFUBDr6")

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

조직 초대

사용자를 조직에 초대하고 대기 중인 초대를 관리합니다.

사용자를 조직에 초대합니다:

client = anthropic.Anthropic()

invite = client.beta.organization.invites.create(
    email="user@example.com", role="developer"
)

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

대기 중인 초대를 나열합니다:

client = anthropic.Anthropic()

invites = client.beta.organization.invites.list(limit=10)

# 필요에 따라 추가 페이지를 자동으로 가져옵니다.
for invite in invites:
    print(f"{invite.id}: {invite.email} ({invite.status})")

초대를 삭제합니다:

client = anthropic.Anthropic()

deleted_invite = client.beta.organization.invites.delete(
    "invite_015gWxHNr6h6TdRPZTmuCGnn"
)

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

워크스페이스

Console 및 API 예제는 워크스페이스를 참조하세요.

워크스페이스 멤버

특정 워크스페이스에 대한 사용자 액세스를 관리합니다:

워크스페이스에 멤버를 추가합니다:

client = anthropic.Anthropic()

member = client.beta.organization.workspaces.members.add(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    user_id="user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_role="workspace_developer",
)

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

워크스페이스의 멤버를 나열합니다:

client = anthropic.Anthropic()

members = client.beta.organization.workspaces.members.list(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", limit=10
)

# 필요에 따라 추가 페이지를 자동으로 가져옵니다.
for member in members:
    print(f"{member.user_id}: {member.workspace_role}")

워크스페이스 멤버의 역할을 업데이트합니다:

client = anthropic.Anthropic()

member = client.beta.organization.workspaces.members.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    workspace_role="workspace_admin",
)

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

워크스페이스에서 멤버를 제거합니다:

client = anthropic.Anthropic()

removed_member = client.beta.organization.workspaces.members.remove(
    "user_01XyDMpzjS89pFZXqSFUBDr6", workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
)

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

API 키

API 키를 모니터링하고 관리합니다. 응답의 각 키에는 expires_at 타임스탬프(만료가 없는 키의 경우 null)와 해당 키가 대리하는 아이덴티티인 principal이 포함됩니다(키 유형 참조). 개인 키의 경우 principal은 {"type": "user_actor", "user_id": "user_..."}이고, 서비스 계정 키의 경우 {"type": "service_account_actor", "service_account_id": "svac_..."}이며, 워크스페이스 키의 경우 null입니다. 각 키에는 scope 객체도 있습니다. 하나의 워크스페이스에 바인딩된 키의 경우 {"type": "workspace", "workspace_id": "wrkspc_..."}이고, 계정이 액세스할 수 있는 모든 워크스페이스에서 작동할 수 있는 키의 경우 {"type": "organization"}입니다. 최상위 workspace_id 필드는 지원 중단되었으며, Default Workspace에 바인딩된 키와 워크스페이스 스코프가 없는 키 모두에 대해 null입니다. 이 둘을 구분하려면 scope를 사용하세요. Default Workspace의 ID로 workspace_id 필터를 적용하여 목록을 조회하면 Default Workspace에 바인딩된 키만 반환됩니다. 워크스페이스 스코프가 없는 키는 어떤 workspace_id 필터로도 반환되지 않습니다.

워크스페이스의 활성 API 키를 나열합니다:

client = anthropic.Anthropic()

api_keys = client.beta.organization.api_keys.list(
    limit=10, status="active", workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
)

# 필요에 따라 추가 페이지를 자동으로 가져옵니다.
for api_key in api_keys:
    print(f"{api_key.id}: {api_key.name} ({api_key.status})")

API 키의 이름을 변경하거나 비활성화합니다:

client = anthropic.Anthropic()

api_key = client.beta.organization.api_keys.update(
    "apikey_01Rj2N8SVvo6BePZj99NhmiT", status="inactive", name="New Key Name"
)

print(f"id: {api_key.id}")
print(f"name: {api_key.name}")
print(f"status: {api_key.status}")

서비스 계정

서비스 계정 키와 Workload Identity Federation 토큰이 대리하는 비인간 아이덴티티인 서비스 계정(svac_...)을 생성하고 관리합니다. 이 엔드포인트는 페더레이션 발급자 및 페더레이션 규칙 엔드포인트와 마찬가지로 org:admin OAuth 토큰이 필요합니다. Admin API로 WIF 관리하기를 참조하세요.

페더레이션 발급자

조직의 워크로드 아이덴티티를 주장할 수 있는 토큰을 발급하는 OIDC 아이덴티티 공급자(fdis_...)를 등록합니다. Admin API로 WIF 관리하기를 참조하세요.

페더레이션 규칙

발급자 토큰을 서비스 계정 및 스코프에 매핑하는 규칙(fdrl_...)을 관리합니다. Admin API로 WIF 관리하기를 참조하세요.

조직 정보 액세스

/v1/organizations/me 엔드포인트는 자격 증명이 속한 조직을 반환합니다:

client = anthropic.Anthropic()

organization = client.beta.organization.retrieve()

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

{
  "id": "12345678-1234-5678-1234-567812345678",
  "type": "organization",
  "name": "Organization Name"
}

매개변수 세부 정보 및 응답 스키마는 조직 정보 API 레퍼런스를 참조하세요.

사용량 및 비용 보고서

사용량 및 비용 API로 조직의 사용량과 비용을 추적하세요.

Claude Code 분석

Claude Code Analytics API로 개발자 생산성과 Claude Code 도입 현황을 모니터링하세요.

속도 제한

Rate Limits API로 조직 및 워크스페이스에 구성된 속도 제한을 조회하세요.

Compliance API

Compliance API로 조직의 감사 및 활동 데이터를 조회하세요. Admin API 키는 Activity Feed만 읽을 수 있습니다. 전체 액세스는 Compliance API 설정을 참조하세요.

모범 사례

• 워크스페이스와 API 키에 의미 있는 이름과 설명을 사용하세요
• 실패한 작업의 오류를 처리하세요
• 멤버 역할과 권한을 정기적으로 감사하세요
• 사용하지 않는 워크스페이스와 만료된 초대를 정리하세요
• API 키 사용량을 모니터링하고, 각 키의 expires_at을 감사하며, 키를 주기적으로 교체하세요

FAQ

워크스페이스 관련 질문은 워크스페이스 FAQ를 참조하세요.