使用 Admin API 管理 WIF

以程式化方式建立和管理 Workload Identity Federation 服務帳戶、簽發者和規則，適用於基礎架構即程式碼和 CI 工作流程。

Admin API 可讓您以程式化方式建立和管理 Workload Identity Federation 資源：服務帳戶、聯合簽發者和聯合規則。您可以使用它將聯合設定保存在「infrastructure as code」（基礎架構即程式碼）中、從 CI 佈建設定，並在多個組織之間重現設定，而不必在 Claude Console 中逐一點選操作。這些端點與 Admin API 的其餘部分共用 /v1/organizations 路徑前綴。

先決條件

本頁上的每個請求都使用帶有 org:admin 範圍的 OAuth bearer token 進行驗證。此範圍僅授予具有管理員、擁有者或主要擁有者角色的組織成員，並授予對整個組織的存取權：任何工作區綁定都會被忽略。取得權杖的方式有兩種，且兩者具有不同的權限：來自您自己登入的權杖以使用者身分運作，而聯合權杖則以服務帳戶身分運作，無法執行本頁上的所有操作。

互動式（您的終端機）

使用 ant CLI 以專用設定檔登入，並請求 org:admin 範圍（請參閱管理員存取），然後匯出 bearer token。使用 --profile admin 登入會將 org:admin 憑證儲存在其專屬的設定檔名稱下，同時也會使其成為 CLI 的作用中設定檔，而匯出的變數會套用至該 shell 中的每個 SDK 和 CLI 呼叫；因此請使用您專門保留給管理用途的 shell，完成後取消設定該變數，並使用 ant profile activate default 將 CLI 切換回來：

CLI

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

互動式權杖的有效期很短；如果請求開始傳回 401，請重新執行匯出命令（它會自動重新整理權杖）。

SDK 和 ant CLI 會自動讀取 ANTHROPIC_AUTH_TOKEN；請在同一個 shell 中保持 ANTHROPIC_API_KEY 未設定，因為這些端點會拒絕 API 金鑰，而當兩者都設定時，每個用戶端都會使用該金鑰。

工作負載（CI 和自動化）

建立一個 oauth_scope: org:admin 的聯合規則，其目標為 organization_role 為 admin 的服務帳戶。該規則本身必須在 Claude Console 中建立：授予工作負載組織管理員存取權是一項刻意的人為操作，而不是自動化可以自行引導完成的事情。下一節將逐步說明這項每個組織只需執行一次的設定。

引導工作負載以管理 WIF

只需一條在 Console 中建立的規則，就足以將其餘的聯合設定納入基礎架構即程式碼：將 org:admin 範圍授予單一受信任的工作負載，並讓該工作負載透過此 API 管理聯合簽發者和每個工作區範圍的聯合規則。

在 Console 中建立 org:admin 規則
在 Claude Console 中，前往 Workload identity 頁面（platform.claude.com/settings/workload-identity-federation），然後選取 Connect workload，為您的自動化工作負載建立一條聯合規則，例如您基礎架構儲存庫中的 GitHub Actions 工作流程。在 Advanced rule options 下，將規則的 OAuth 範圍設定為 org:admin：精靈接著會以 Admin 組織角色建立新的服務帳戶（或要求您選擇一個現有的管理員服務帳戶作為目標）。
請將規則比對到一個確切的工作負載身分，而不是廣泛的模式。除非 subject_prefix 以 * 結尾，否則它是完全比對。對於 GitHub Actions，請將主體固定到受保護的分支，例如 repo:my-org/my-repo:ref:refs/heads/main。像 repo:my-org/my-repo:* 這樣的結尾萬用字元也會比對到 pull_request 執行，包括從分支（fork）觸發的執行，因此任何能夠對該儲存庫開啟 pull request 的人都可能鑄造出 org:admin 權杖。請參閱限制哪些工作流程可以進行驗證。
2
交換工作負載的身分權杖
使用其中一個 SDK 或 ant CLI 的工作負載不需要自行執行交換。使用聯合環境變數將用戶端指向該規則，並以不帶引數的方式建構它，與建構 SDK 用戶端中用於推論的方式完全相同；用戶端會在第一個請求時交換身分權杖，並在產生的存取權杖到期之前，重新讀取身分權杖並再次交換：
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 會在每個程序中再次交換身分權杖，而帶有 jti 宣告的身分權杖（GitHub Actions 權杖即是如此）只會被接受一次，因此第二個命令會被拒絕；當規則對所有工作區或多個工作區啟用時，設定檔也是為 CLI 提供交換所需 workspace_id 的唯一方式，因為與 SDK 不同，CLI 不會將 ANTHROPIC_WORKSPACE_ID 或 --workspace-id 傳入交換中。每個 SDK 也接受相同的設定作為明確的建構函式引數，各語言的用法請參閱建構 SDK 用戶端。完整清單和優先順序請參閱環境變數和憑證優先順序。
使用 curl 呼叫 API 的工作負載會自行將 JWT 交換為短期的 org:admin bearer token，使用與任何其他聯合工作負載相同的權杖交換，並在 authorization: Bearer 標頭中傳送該權杖。
透過 API 管理簽發者和工作區範圍的規則
設定好用戶端後（或者對於 curl，將鑄造的權杖放在 ANTHROPIC_AUTH_TOKEN 中），工作負載即可使用本頁上的端點建立和管理您的聯合設定。

關於工作負載鑄造的權杖可以和不能執行的操作，請參閱權限與限制。如果您已經使用 Connect workload 精靈建立了簽發者、服務帳戶或規則，請使用以下端點列出它們，並將它們匯入您的基礎架構即程式碼狀態中，而不是重新建立。

驗證

所有端點都位於 https://api.anthropic.com/v1/organizations/ 之下。對聯合和服務帳戶端點的每個請求都需要 API 版本標頭和 bearer token：

在 SDK 中，這些端點為 client.organization.service_accounts、client.organization.federation.issuers 和 client.organization.federation.rules（在 CLI 中為 ant organization:service-accounts、federation:issuers 和 federation:rules）。SDK 和 CLI 範例會建構預設用戶端，該用戶端會傳送來自 ANTHROPIC_AUTH_TOKEN 的 bearer token，或者在自動化工作負載中，如引導工作負載以管理 WIF 所述自行執行聯合交換。SDK 的列出方法會視需要擷取後續頁面，因此 limit 設定的是頁面大小；PHP 和 Ruby 範例只讀取一頁。

client = anthropic.Anthropic()

service_accounts = client.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_...）是聯合權杖所代表的非人類身分。請將 organization_role 設定為 developer。

建立服務帳戶：

client = anthropic.Anthropic()

service_account = client.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.organization.service_accounts.list(limit=20)

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

封存服務帳戶：

client = anthropic.Anthropic()

service_account = client.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 身分提供者。jwks 欄位是一個可辨識聯集（discriminated union），用於控制 Anthropic 如何擷取提供者的簽署金鑰：

`jwks` 值	使用時機
`{"type": "discovery"}`	提供者在簽發者 URL 提供 `/.well-known/openid-configuration`。
`{"type": "explicit_url", "url": "..."}`	直接指向 JWKS 端點。
`{"type": "inline", "keys": [...]}`	為無法從公用網際網路存取的提供者上傳金鑰集。

註冊簽發者。此範例使用 JWKS 探索註冊 GitHub Actions：

client = anthropic.Anthropic()

issuer = client.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.organization.federation.issuers.list(limit=20)

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

封存簽發者：

client = anthropic.Anthropic()

issuer = client.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_scope 不是 workspace:developer 或 workspace:inference，OAuth 呼叫者就無法更新該簽發者；請參閱權限與限制。

如需完整的參數詳細資訊和回應結構描述，請參閱聯合簽發者 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.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.organization.federation.rules.list(
    issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)

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

封存規則：

client = anthropic.Anthropic()

rule = client.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 參考：服務帳戶和聯合端點的自動產生請求與回應結構描述

先決條件

互動式（您的終端機）

工作負載（CI 和自動化）

引導工作負載以管理 WIF

在 Console 中建立 org:admin 規則

交換工作負載的身分權杖

透過 API 管理簽發者和工作區範圍的規則

驗證

服務帳戶

聯合簽發者

聯合規則

權限與限制

分頁與封存

另請參閱