管理驗證

使用 Admin API 管理 WIF

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

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

先決條件

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

互動式（您的終端機）： 使用 ant CLI 在專用的設定檔下登入，並請求 org:admin 範圍（請參閱管理員存取權限），然後匯出 bearer token：

CLI

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

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

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

引導工作負載以管理 WIF

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

在 Console 中建立 org:admin 規則
在 Claude Console 中，前往 Settings → Workload identity 並選擇 Connect workload，為您的自動化工作負載建立一個聯合規則，例如您基礎架構儲存庫中的 GitHub Actions 工作流程。在 Advanced rule options 下，將規則的 OAuth 範圍設定為 org:admin：精靈接著會建立具有 Admin 組織角色的新服務帳戶（或要求您選擇現有的管理員服務帳戶作為目標）。
將規則比對到一個確切的工作負載身分，而非寬泛的模式。subject_prefix 是精確比對，除非它以 * 結尾。對於 GitHub Actions，請將 subject 固定到受保護的分支，例如 repo:my-org/my-repo:ref:refs/heads/main。尾隨萬用字元（例如 repo:my-org/my-repo:*）也會比對到 pull_request 執行，包括從 fork 觸發的執行，因此任何能對該儲存庫開啟 pull request 的人都可以鑄造 org:admin token。請參閱限制哪些工作流程可以進行驗證。
交換工作負載的身分 token
在執行階段，工作負載使用與任何其他聯合工作負載相同的 token 交換，將來自其身分提供者的 JWT 交換為短期有效的 org:admin bearer token。
透過 API 管理簽發者和工作區範圍的規則
將鑄造的 token 存入 ANTHROPIC_OAUTH_TOKEN 後，工作負載即可使用本頁面上的端點建立和管理您的聯合設定。

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

驗證

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

cURL

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

cURL

# 建立服務帳戶
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。服務帳戶必須是工作區的成員，聯合 token 才能在該工作區中運作。每個服務帳戶在您組織的預設工作區中都有隱含的成員資格；若要為其他工作區新增明確的成員資格，請對 /v1/organizations/service_accounts/{service_account_id}/workspaces 使用 GET、POST 和 DELETE，其中 DELETE 的目標為 .../workspaces/{workspace_id}。

聯合簽發者

聯合簽發者（fdis_...）會向您的組織註冊 OIDC 身分提供者。jwks 欄位是一個判別聯集，用於控制 Anthropic 如何擷取提供者的簽署金鑰：

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

cURL

# 註冊簽發者（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 可以鑄造以該規則目標身分運作的 token。建立請求中的 workspace_id 會在建立時於該工作區中啟用規則；之後可透過 /federation_rules/{rule_id}/workspaces 子資源新增更多工作區。建立時必須提供 workspace_id 或 applies_to_all_workspaces: true 其中之一。

cURL

# 建立規則（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。若要管理規則可在其中鑄造 token 的工作區，請對 /v1/organizations/federation_rules/{rule_id}/workspaces 使用 GET 和 POST，並對 /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id} 使用 DELETE。

權限與限制

經 OAuth 驗證的呼叫者只能建立或修改 oauth_scope 為 workspace:developer 或 workspace:inference 的規則。若要建立或修改具有任何其他範圍（例如 org:admin 或 org:manage_tunnels）的規則，請使用 Console。
OAuth 呼叫者無法更新支援 oauth_scope 不是 workspace:developer 或 workspace:inference（例如 org:admin 或 org:manage_tunnels）之規則的聯合簽發者。建議為引導規則註冊專用的簽發者，以便工作區範圍規則背後的簽發者仍可透過 API 更新。
這些端點不接受 Admin API 金鑰，無論是讀取或寫入；請使用 org:admin OAuth token。

具有 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 端點的自動產生請求和回應結構描述

Was this page helpful?

管理驗證

使用 Admin API 管理 WIF

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

先決條件

互動式（您的終端機）： 使用 ant CLI 在專用的設定檔下登入，並請求 org:admin 範圍（請參閱管理員存取權限），然後匯出 bearer token：

CLI

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

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

引導工作負載以管理 WIF

在 Console 中建立 org:admin 規則
在 Claude Console 中，前往 Settings → Workload identity 並選擇 Connect workload，為您的自動化工作負載建立一個聯合規則，例如您基礎架構儲存庫中的 GitHub Actions 工作流程。在 Advanced rule options 下，將規則的 OAuth 範圍設定為 org:admin：精靈接著會建立具有 Admin 組織角色的新服務帳戶（或要求您選擇現有的管理員服務帳戶作為目標）。
將規則比對到一個確切的工作負載身分，而非寬泛的模式。subject_prefix 是精確比對，除非它以 * 結尾。對於 GitHub Actions，請將 subject 固定到受保護的分支，例如 repo:my-org/my-repo:ref:refs/heads/main。尾隨萬用字元（例如 repo:my-org/my-repo:*）也會比對到 pull_request 執行，包括從 fork 觸發的執行，因此任何能對該儲存庫開啟 pull request 的人都可以鑄造 org:admin token。請參閱限制哪些工作流程可以進行驗證。
交換工作負載的身分 token
在執行階段，工作負載使用與任何其他聯合工作負載相同的 token 交換，將來自其身分提供者的 JWT 交換為短期有效的 org:admin bearer token。
透過 API 管理簽發者和工作區範圍的規則
將鑄造的 token 存入 ANTHROPIC_OAUTH_TOKEN 後，工作負載即可使用本頁面上的端點建立和管理您的聯合設定。

驗證

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

cURL

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

cURL

# 建立服務帳戶
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",
  "...": "..."
}

聯合簽發者

聯合簽發者（fdis_...）會向您的組織註冊 OIDC 身分提供者。jwks 欄位是一個判別聯集，用於控制 Anthropic 如何擷取提供者的簽署金鑰：

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

cURL

# 註冊簽發者（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"

聯合規則

cURL

# 建立規則（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": "..."
}

權限與限制

經 OAuth 驗證的呼叫者只能建立或修改 oauth_scope 為 workspace:developer 或 workspace:inference 的規則。若要建立或修改具有任何其他範圍（例如 org:admin 或 org:manage_tunnels）的規則，請使用 Console。
OAuth 呼叫者無法更新支援 oauth_scope 不是 workspace:developer 或 workspace:inference（例如 org:admin 或 org:manage_tunnels）之規則的聯合簽發者。建議為引導規則註冊專用的簽發者，以便工作區範圍規則背後的簽發者仍可透過 API 更新。
這些端點不接受 Admin API 金鑰，無論是讀取或寫入；請使用 org:admin OAuth token。

分頁與封存

另請參閱

Workload Identity Federation：概念與 Console 設定逐步說明
WIF 參考：環境變數、驗證規則、OAuth 範圍和錯誤代碼
Admin API：其餘的組織管理介面
Admin API 參考：每個 Admin API 端點的自動產生請求和回應結構描述

Was this page helpful?

先決條件

引導工作負載以管理 WIF

驗證

服務帳戶

聯合簽發者

聯合規則

權限與限制

分頁與封存

另請參閱

先決條件

引導工作負載以管理 WIF

驗證

服務帳戶

聯合簽發者

聯合規則

權限與限制

分頁與封存

另請參閱

先決條件

引導工作負載以管理 WIF

驗證

服務帳戶

聯合簽發者

聯合規則

權限與限制

分頁與封存

另請參閱

先決條件

引導工作負載以管理 WIF

驗證

服務帳戶

聯合簽發者

聯合規則

權限與限制

分頁與封存

另請參閱