使用 Admin API 管理 WIF

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

先決條件

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

互動式（您的終端機）

使用 ant CLI 以專用設定檔登入，並請求 org:admin 範圍（請參閱管理員存取），然後匯出 bearer 權杖。使用 --profile admin 登入會將 org:admin 憑證儲存在其專屬的設定檔名稱下，同時也會將其設為 CLI 的作用中設定檔，而匯出的變數會套用至該 shell 中的每個 SDK 與 CLI 呼叫；因此請使用您專門保留給管理用途的 shell，完成後取消設定該變數，並使用 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，請重新執行匯出指令（它會自動重新整理權杖）。

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 管理聯合簽發者以及每一條工作區範圍的聯合規則。

1. 1

   在 Console 中建立 org:admin 規則

   在 Claude Console 中，前往 Settings → Workload identity 並選取 Connect workload，為您的自動化工作負載建立一條聯合規則，例如您基礎設施儲存庫中的 GitHub Actions 工作流程。在 Advanced rule options 下，將規則的 OAuth 範圍設為 org:admin：精靈接著會以 Admin 組織角色建立新的服務帳戶（或要求您選擇一個現有的管理員服務帳戶作為目標）。

2. 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 權杖，使用與任何其他聯合工作負載相同的權杖交換，並在 authorization: Bearer 標頭中傳送它。

3. 3

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

   用戶端設定完成後（或者對於 curl，將鑄造出的權杖放入 ANTHROPIC_AUTH_TOKEN），工作負載即可使用本頁的端點建立並管理您的聯合設定。

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

驗證

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

在 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 的 bearer 權杖，或者在自動化工作負載中，如啟動一個工作負載來管理 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_...）是聯合權杖所代表的非人類身分。請將 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}")

封存服務帳戶：

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

註冊簽發者。此範例以 JWKS 探索方式註冊 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 端點的自動產生請求與回應結構描述