Admin API로 WIF 관리하기

Admin API를 사용하면 Workload Identity Federation 리소스, 즉 서비스 계정(service accounts), 페더레이션 발급자(federation issuers), 페더레이션 규칙(federation rules)을 프로그래밍 방식으로 생성하고 관리할 수 있습니다. 이를 사용하면 Claude Console에서 일일이 클릭하는 대신 페더레이션 구성을 "infrastructure as code"(인프라스트럭처 코드화)로 유지하고, CI에서 프로비저닝하며, 여러 조직에 걸쳐 재현할 수 있습니다. 이 엔드포인트들은 나머지 Admin API와 /v1/organizations 경로 접두사를 공유합니다.

사전 요구 사항

이 페이지의 모든 요청은 org:admin 스코프를 가진 OAuth 베어러 토큰(bearer token)으로 인증합니다. 이 스코프는 admin, owner 또는 primary owner 역할을 가진 조직 구성원에게만 부여되며, 조직 전체에 대한 액세스 권한을 부여합니다. 즉, 워크스페이스 바인딩은 무시됩니다. 토큰을 얻는 방법은 두 가지이며, 각각 다른 권한을 가집니다. 본인의 로그인으로 얻은 토큰은 사용자로서 동작하는 반면, 페더레이션된 토큰은 서비스 계정으로서 동작하며 이 페이지의 모든 작업을 수행할 수는 없습니다.

대화형 (터미널)

전용 프로필로 ant CLI에 로그인하면서 org:admin 스코프를 요청한 다음(관리자 액세스 참조), 베어러 토큰을 내보내세요. --profile admin으로 로그인하면 org:admin 자격 증명이 자체 프로필 이름으로 저장되고 CLI의 활성 프로필로도 설정되며, 내보낸 변수는 해당 셸의 모든 SDK 및 CLI 호출에 적용됩니다. 따라서 관리 전용으로 사용하는 셸을 사용하고, 작업이 끝나면 변수를 해제하고, 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을 자동으로 읽습니다. 같은 셸에서 ANTHROPIC_API_KEY는 설정하지 않은 상태로 두세요. 이 엔드포인트들은 API 키를 거부하며, 일부 클라이언트는 둘 다 설정된 경우 키를 우선하기 때문입니다.

워크로드 (CI 및 자동화)

organization_role이 admin인 서비스 계정을 대상으로 하는 oauth_scope: org:admin 페더레이션 규칙을 생성하세요. 규칙 자체는 Claude Console에서 생성해야 합니다. 워크로드에 조직 관리자 액세스 권한을 부여하는 것은 의도적인 사람의 행위여야 하며, 자동화가 스스로 부트스트랩할 수 있는 것이 아닙니다. 다음 섹션에서 조직당 한 번 수행하는 이 설정 과정을 안내합니다.

WIF를 관리할 워크로드 부트스트랩하기

Console에서 생성한 규칙 하나만 있으면 나머지 페더레이션 구성을 infrastructure as code로 관리할 수 있습니다. 신뢰할 수 있는 단일 워크로드에 org:admin 스코프를 부여하고, 해당 워크로드가 이 API를 통해 페더레이션 발급자와 모든 워크스페이스 범위 페더레이션 규칙을 관리하도록 하세요.

1. 1

   Console에서 org:admin 규칙 생성하기

   Claude Console에서 Settings → Workload identity로 이동하고 Connect workload를 선택하여 자동화 워크로드(예: 인프라 리포지토리의 GitHub Actions 워크플로)를 위한 페더레이션 규칙 하나를 생성하세요. Advanced rule options에서 규칙의 OAuth 스코프를 org:admin으로 설정하세요. 그러면 마법사가 Admin 조직 역할을 가진 새 서비스 계정을 생성합니다(또는 기존 admin 서비스 계정을 대상으로 선택하도록 요청합니다).

2. 2

   워크로드의 ID 토큰 교환하기

   SDK 중 하나 또는 ant CLI를 사용하는 워크로드는 교환을 직접 수행하지 않습니다. SDK 클라이언트 구성하기의 추론용 설정과 정확히 동일하게, 페더레이션 환경 변수로 클라이언트가 규칙을 가리키도록 하고 인수 없이 클라이언트를 생성하세요. 클라이언트는 첫 번째 요청 시 ID 토큰을 교환하고, 결과 액세스 토큰이 만료되기 전에 ID 토큰을 다시 읽어 다시 교환합니다:

   export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...        # the org:admin rule from step 1
   export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
   export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...       # the rule's target service account
   export ANTHROPIC_IDENTITY_TOKEN_FILE=/path/to/jwt  # or ANTHROPIC_IDENTITY_TOKEN
   # ANTHROPIC_WORKSPACE_ID는 규칙이 모든 워크스페이스 또는 둘 이상의
   # 워크스페이스에 활성화된 경우에만 필요합니다. org:admin 엔드포인트는 바인딩을 무시합니다.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   ant CLI는 동일한 변수를 읽거나 --federation-rule, --organization-id, --service-account-id, --identity-token-file 플래그를 받습니다. 둘 이상의 ant 명령을 실행하는 워크로드의 경우 플래그나 환경 변수 대신 페더레이션 프로필을 사용하세요. 플래그나 변수를 사용하면 CLI가 모든 프로세스에서 ID 토큰을 다시 교환하는데, jti 클레임을 가진 ID 토큰(GitHub Actions 토큰이 그렇습니다)은 한 번만 허용되므로 두 번째 명령은 거부됩니다. 또한 규칙이 모든 워크스페이스 또는 둘 이상의 워크스페이스에 대해 활성화된 경우, 프로필은 교환을 위해 CLI에 workspace_id를 제공하는 유일한 방법입니다. SDK와 달리 CLI는 ANTHROPIC_WORKSPACE_ID나 --workspace-id를 교환에 전달하지 않기 때문입니다. 모든 SDK는 동일한 설정을 명시적 생성자 인수로도 받으며, 이는 SDK 클라이언트 구성하기에 언어별로 나와 있습니다. 전체 목록과 순서는 환경 변수 및 자격 증명 우선순위를 참조하세요.

   curl로 API를 호출하는 워크로드는 다른 페더레이션 워크로드와 동일한 토큰 교환을 사용하여 JWT를 수명이 짧은 org:admin 베어러 토큰으로 직접 교환하고, 이를 authorization: Bearer 헤더에 담아 보냅니다.

3. 3

   API를 통해 발급자 및 워크스페이스 범위 규칙 관리하기

   클라이언트가 구성되면(또는 curl의 경우 발급된 토큰이 ANTHROPIC_AUTH_TOKEN에 있으면), 워크로드는 이 페이지의 엔드포인트를 사용하여 페더레이션 구성을 생성하고 관리합니다.

워크로드가 발급한 토큰이 수행할 수 있는 작업과 수행할 수 없는 작업은 권한 및 제약 조건을 참조하세요. Connect workload 마법사로 이미 발급자, 서비스 계정 또는 규칙을 생성했다면, 다시 생성하는 대신 다음 엔드포인트로 목록을 조회하여 infrastructure-as-code 상태로 가져오세요.

인증

모든 엔드포인트는 https://api.anthropic.com/v1/organizations/ 아래에 있습니다. 페더레이션 및 서비스 계정 엔드포인트에 대한 모든 요청에는 API 버전 헤더와 베어러 토큰이 필요합니다:

SDK에서 이 엔드포인트들은 client.beta.organization.service_accounts, client.beta.organization.federation.issuers, client.beta.organization.federation.rules입니다(CLI에서는 ant beta:organization:service-accounts, federation:issuers, federation:rules). SDK 및 CLI 예제는 기본 클라이언트를 생성하며, 이 클라이언트는 ANTHROPIC_AUTH_TOKEN의 베어러 토큰을 보내거나, 자동화된 워크로드에서는 WIF를 관리할 워크로드 부트스트랩하기에 설명된 대로 페더레이션 교환을 직접 수행합니다. SDK의 list 메서드는 필요에 따라 추가 페이지를 가져오므로 limit은 페이지 크기를 설정합니다. PHP 및 Ruby 예제는 한 페이지를 읽습니다.

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list()

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Admin API 키는 이 엔드포인트들에서 허용되지 않습니다. Admin API 페이지의 x-api-key 예제는 여기에 적용되지 않습니다.

서비스 계정

서비스 계정(svac_...)은 페더레이션된 토큰이 그 역할로 동작하는 비인간 ID입니다. organization_role을 developer로 설정하세요.

서비스 계정 생성:

client = anthropic.Anthropic()

service_account = client.beta.organization.service_accounts.create(
    name="inference-worker", organization_role="developer"
)

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

서비스 계정 목록 조회:

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list(limit=20)

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

서비스 계정 보관(archive):

client = anthropic.Anthropic()

service_account = client.beta.organization.service_accounts.archive(
    "svac_01ABCDEFabcdef0123456789XY"
)

print(f"id: {service_account.id}")
print(f"archived_at: {service_account.archived_at}")

생성 엔드포인트는 새 서비스 계정을 반환합니다:

{
  "id": "svac_...",
  "name": "inference-worker",
  "organization_role": "developer",
  "created_at": "...",
  "type": "service_account",
  "...": "..."
}

단일 서비스 계정을 읽거나 업데이트하려면 /v1/organizations/service_accounts/{service_account_id}에 GET 및 POST를 사용하세요. 페더레이션된 토큰이 워크스페이스에서 동작하려면 서비스 계정이 먼저 해당 워크스페이스의 구성원이어야 합니다. 모든 서비스 계정은 조직의 기본 워크스페이스에 암묵적 멤버십을 가집니다. 다른 워크스페이스에 대한 명시적 멤버십은 /v1/organizations/service_accounts/{service_account_id}/workspaces에 GET, POST, DELETE를 사용하여 추가하세요. 여기서 DELETE는 .../workspaces/{workspace_id}를 대상으로 합니다.

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

페더레이션 발급자

페더레이션 발급자(fdis_...)는 OIDC ID 공급자를 조직에 등록합니다. jwks 필드는 Anthropic이 공급자의 서명 키를 가져오는 방식을 제어하는 구별된 유니온(discriminated union)입니다:

발급자를 등록합니다. 이 예제는 JWKS discovery로 GitHub Actions를 등록합니다:

client = anthropic.Anthropic()

issuer = client.beta.organization.federation.issuers.create(
    name="github-actions",
    issuer_url="https://token.actions.githubusercontent.com",
    jwks={"type": "discovery"},
)

print(f"id: {issuer.id}")
print(f"name: {issuer.name}")
print(f"issuer_url: {issuer.issuer_url}")

발급자 목록 조회:

client = anthropic.Anthropic()

issuers = client.beta.organization.federation.issuers.list(limit=20)

for issuer in issuers:
    print(f"{issuer.id}: {issuer.name}")

발급자 보관:

client = anthropic.Anthropic()

issuer = client.beta.organization.federation.issuers.archive(
    "fdis_01ABCDEFabcdef0123456789XY"
)

print(f"id: {issuer.id}")
print(f"archived_at: {issuer.archived_at}")

단일 발급자를 읽거나 업데이트하려면 /v1/organizations/federation_issuers/{issuer_id}에 GET 및 POST를 사용하세요. OAuth 호출자는 oauth_scope가 workspace:developer 또는 workspace:inference 이외의 값인 규칙을 뒷받침하는 발급자를 업데이트할 수 없습니다. 권한 및 제약 조건을 참조하세요.

전체 매개변수 세부 정보와 응답 스키마는 페더레이션 발급자 API 레퍼런스를 참조하세요.

페더레이션 규칙

페더레이션 규칙(fdrl_...)은 발급자를 서비스 계정에 바인딩합니다. 규칙의 매칭 조건을 충족하는 발급자의 JWT는 규칙의 대상으로 동작하는 토큰을 발급할 수 있습니다. 생성 요청의 workspace_id는 생성 시 해당 워크스페이스에서 규칙을 활성화합니다. 나중에 /federation_rules/{rule_id}/workspaces 하위 리소스를 통해 더 많은 워크스페이스를 추가하세요. 생성 시 workspace_id 또는 applies_to_all_workspaces: true 중 하나가 필요합니다.

규칙을 생성합니다. 이 예제는 main 브랜치에서의 GitHub Actions 배포가 서비스 계정으로 동작하도록 허용합니다:

client = anthropic.Anthropic()

rule = client.beta.organization.federation.rules.create(
    name="gha-deploy",
    issuer_id="fdis_01ABCDEFabcdef0123456789XY",
    match={
        "subject_prefix": "repo:my-org/my-repo:ref:refs/heads/main",
        "claims": {"repository_owner": "my-org"},
    },
    target={
        "type": "service_account",
        "service_account_id": "svac_01ABCDEFabcdef0123456789XY",
    },
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    oauth_scope="workspace:developer",
    token_lifetime_seconds=600,
)

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

규칙 목록 조회(선택적으로 발급자로 필터링):

client = anthropic.Anthropic()

rules = client.beta.organization.federation.rules.list(
    issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)

for rule in rules:
    print(f"{rule.id}: {rule.name}")

규칙 보관:

client = anthropic.Anthropic()

rule = client.beta.organization.federation.rules.archive(
    "fdrl_01ABCDEFabcdef0123456789XY"
)

print(f"id: {rule.id}")
print(f"archived_at: {rule.archived_at}")

목록 엔드포인트는 규칙 한 페이지와 다음 페이지를 위한 커서를 반환합니다:

{
  "data": [{ "id": "fdrl_...", "name": "gha-deploy", "...": "..." }],
  "next_page": "..."
}

단일 규칙을 읽거나 업데이트하려면 /v1/organizations/federation_rules/{rule_id}에 GET 및 POST를 사용하세요. 규칙이 토큰을 발급할 수 있는 워크스페이스를 관리하려면 /v1/organizations/federation_rules/{rule_id}/workspaces에 GET 및 POST를, /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}에 DELETE를 사용하세요.

전체 매개변수 세부 정보와 응답 스키마는 페더레이션 규칙 API 레퍼런스를 참조하세요.

권한 및 제약 조건

oauth_scope: org:admin인 규칙은 organization_role이 admin인 서비스 계정을 대상으로 해야 합니다. 리소스 이름은 ^[a-z0-9-]+$와 일치해야 하고, 1~255자여야 하며, 각 리소스 유형별로 조직 내에서 고유해야 합니다. 전체 필드 수준 제약 조건은 유효성 검사 규칙을 참조하세요.

페이지네이션 및 보관

서비스 계정, 페더레이션 발급자, 페더레이션 규칙 목록 엔드포인트는 limit(1~100, 기본값 20)과 이전 응답에서 가져온 page 커서를 받습니다. 응답의 next_page 값을 다음 요청의 page 쿼리 매개변수로 전달하세요. 규칙-워크스페이스 하위 리소스 목록은 페이지네이션 없이 전체 세트를 반환합니다. 보관된 리소스는 기본적으로 목록에서 숨겨집니다. 포함하려면 include_archived=true를 전달하세요.

보관은 소프트 삭제이며 멱등적입니다. 이미 보관된 리소스를 보관해도 성공합니다. 활성 페더레이션 규칙이 여전히 참조하고 있는 동안 발급자나 서비스 계정을 보관하면 400이 반환됩니다. 먼저 규칙을 보관하세요.

참고 항목

• Workload Identity Federation: 개념 및 Console 설정 안내
• WIF 레퍼런스: 환경 변수, 유효성 검사 규칙, OAuth 스코프, 오류 코드
• Admin API: 나머지 조직 관리 기능
• Admin API 레퍼런스: 모든 Admin API 엔드포인트에 대해 생성된 요청 및 응답 스키마