Admin API로 WIF 관리하기

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



사전 요구 사항

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



대화형 (터미널)

전용 프로필로 ant CLI에 로그인하면서 org:admin 스코프를 요청하고(관리자 접근 참조), bearer 토큰을 내보냅니다:

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

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



인증

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

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  -H "anthropic-version: 2023-06-01" \
  -H "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

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

# 서비스 계정 보관 처리
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "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}를 대상으로 합니다.

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



페더레이션 발급자

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

# 발급자 등록 (GitHub Actions, JWKS 검색 사용)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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

단일 발급자를 읽거나 업데이트하려면 /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 중 하나가 필요합니다.

# 규칙 생성 (GitHub Actions가 main 브랜치에서 배포)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "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_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# 규칙 보관 처리
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "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를 사용하세요.

전체 매개변수 세부 정보와 응답 스키마는 페더레이션 규칙 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 엔드포인트에 대해 생성된 요청 및 응답 스키마