Admin API로 WIF 관리하기

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



사전 요구 사항

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

대화형(터미널에서): ant CLI를 사용하여 전용 프로필로 로그인하고 org:admin 스코프를 요청한 다음(관리자 액세스 참조), 베어러 토큰을 내보내세요.

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

대화형 토큰은 수명이 짧습니다. 요청이 401을 반환하기 시작하면 내보내기 명령을 다시 실행하세요(토큰이 자동으로 새로 고쳐집니다).

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



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

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

워크로드가 발급한 토큰으로 수행할 수 있는 작업과 수행할 수 없는 작업은 권한 및 제약 사항을 참조하세요. Connect workload 마법사로 이미 발급자, 서비스 계정 또는 규칙을 생성한 경우, 다음 엔드포인트로 목록을 조회하여 다시 생성하는 대신 인프라스트럭처 애즈 코드 상태로 가져오세요.



인증

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

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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



서비스 계정

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

# 서비스 계정 생성
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# 서비스 계정 목록 조회
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# 서비스 계정 보관
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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

{
  "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}를 대상으로 합니다.



페더레이션 발급자

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

# 발급자 등록 (GitHub Actions, JWKS 디스커버리 사용)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "github-actions",
    "issuer_url": "https://token.actions.githubusercontent.com",
    "jwks": {"type": "discovery"}
  }'

# 발급자 목록 조회
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# 발급자 보관 처리
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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



페더레이션 규칙

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

# 규칙 생성 (GitHub Actions가 main 브랜치에서 배포)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "gha-deploy",
    "issuer_id": "fdis_...",
    "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_..."
    },
    "workspace_id": "wrkspc_...",
    "oauth_scope": "workspace:developer",
    "token_lifetime_seconds": 600
  }'

# 규칙 나열, 선택적으로 발급자별 필터링
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules?issuer_id=fdis_..." \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# 규칙 보관
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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

{
  "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를 사용하세요.



권한 및 제약 사항

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 엔드포인트에 대해 생성된 요청 및 응답 스키마