管理驗證

WIF 參考

Workload Identity Federation 的環境變數、驗證規則、設定檔配置與錯誤參考。

本頁彙整了 Workload Identity Federation 的配置介面、驗證限制與錯誤對應。如需設定逐步說明，請參閱身分提供者指南。

權杖交換請求

POST /v1/oauth/token 接受使用 RFC 7523 jwt-bearer 授權類型的 JSON 主體。SDK 會根據環境變數為您建構此請求；各身分提供者指南中的 cURL 範例則顯示原始主體。

欄位	必填	說明
`grant_type`	是	一律為 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	是	由您的身分提供者簽發的 OIDC JWT。
`federation_rule_id`	是	要評估的聯邦規則的標記 ID（`fdrl_...`）。
`organization_id`	是	您的 Anthropic 組織的 UUID。
`service_account_id`	是	目標服務帳戶的標記 ID（`svac_...`）。
`workspace_id`	視情況而定	要將鑄造的權杖限定範圍的工作區標記 ID（`wrkspc_...`），或使用字面值 `default` 代表組織的預設工作區。當規則在多個工作區啟用時為必填。省略時，伺服器會選擇該規則唯一啟用的工作區。

權杖交換回應

POST /v1/oauth/token 回傳標準的 OAuth 2.0 權杖回應（RFC 6749 §5.1）：

欄位	類型	說明
`access_token`	string	短效的 Anthropic 權杖，前綴為 `sk-ant-oat01-...`。以 `Authorization: Bearer <token>` 形式傳遞。
`token_type`	string	一律為 `Bearer`。
`expires_in`	integer	權杖到期前的秒數。
`scope`	string	由匹配規則授予的 OAuth 範圍。

環境變數

SDK 會讀取這些變數，以在不需建構函式引數的情況下執行聯邦權杖交換。

變數	必填	說明	範例
`ANTHROPIC_FEDERATION_RULE_ID`	是	要評估的聯邦規則的標記 ID。	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	是	您的 Anthropic 組織的 UUID。可在 Claude Console 的 Settings > Organization 中找到。	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	由您的「identity provider」（身分提供者），即 IdP 簽發的 JWT 的檔案系統路徑。SDK 在每次交換時都會重新讀取此檔案，以確保在磁碟上輪替的投射權杖始終是最新的。	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	以字串形式表示的 JWT 字面值。當您的平台以環境變數而非檔案的方式注入權杖時使用。	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	是	簽發的存取權杖所代表的目標 Anthropic 服務帳戶的標記 ID。	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	視情況而定	要將鑄造的權杖限定範圍的工作區標記 ID，或使用字面值 `default`。當聯邦規則在多個工作區啟用時為必填；當規則綁定到單一工作區時為選填。鑄造的權杖在交換時即限定於此工作區，因此切換工作區需要進行新的交換。	`wrkspc_...`
`ANTHROPIC_PROFILE`	否	要載入的配置設定檔名稱。優先於本表中的聯邦環境變數。	`staging-profile`

只有當 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID，以及 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN 其中之一全部設定時，直接環境變數聯邦路徑才會啟用。ANTHROPIC_WORKSPACE_ID 會一併讀取，但不影響啟用條件。

設定為空字串的變數仍會佔據其在憑證優先順序鏈中的位置。如果匯出了 ANTHROPIC_API_KEY=""，SDK 會選擇使用空金鑰的 API 金鑰路徑，而不會繼續落到聯邦路徑。請取消設定未使用的憑證變數，而不是將其設為空白。

憑證優先順序

SDK 依此順序解析憑證。第一個產生憑證的來源勝出。

順序	來源	備註
1	建構函式引數（`api_key=`、`auth_token=`、`credentials=`）	一律覆蓋其他所有來源。
2	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`	完全遮蔽聯邦。從 API 金鑰遷移時請取消設定這些變數。
3	`ANTHROPIC_PROFILE`	載入 `<config_dir>/configs/<name>.json`。指定名稱的設定檔不存在時會產生錯誤，而非繼續往下嘗試。
4	聯邦環境變數	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`。
5	作用中設定檔	從 `<config_dir>/active_config` 解析，若無則回退到名為 `default` 的設定檔。

載入設定檔時，環境變數會填補設定檔省略的任何欄位，但絕不會覆蓋設定檔明確設定的欄位。例如，只有當作用中設定檔未設定 workspace_id 時，ANTHROPIC_WORKSPACE_ID 才會填入該欄位。

設定檔配置檔案

設定檔是 SDK 和 ant CLI 都會讀取的具名配置檔案。設定檔讓您可以將聯邦參數隨容器映像一起發佈，或在不更改程式碼的情況下切換環境。

配置目錄

SDK 依此順序尋找配置目錄：

$ANTHROPIC_CONFIG_DIR
Linux 和 macOS 上的 ~/.config/anthropic
Windows 上的 %APPDATA%\Anthropic

作用中設定檔

作用中設定檔名稱依此順序解析：

$ANTHROPIC_PROFILE
<config_dir>/active_config 的內容（由 ant profile activate <name> 寫入的單行檔案）
字面名稱 default

Claude Code 和 Claude Agent SDK 遵循相同的解析順序，因此在此配置的聯邦設定檔也能在無需額外設定的情況下為這些工具進行驗證。

檔案配置

路徑	內容	敏感性
`<config_dir>/configs/<profile>.json`	`version`、`authentication` 區塊、`organization_id`、`workspace_id` 和 `base_url`。	非機密。可安全提交或烘焙到映像中。
`<config_dir>/credentials/<profile>.json`	`version`、快取的 `access_token`、`expires_at`，以及（互動式登入時的）`refresh_token`。	機密。由 SDK 以 `0600` 模式寫入。

配置檔案和憑證檔案都帶有頂層字串 version 欄位，格式為 major.minor（目前為 "1.0"）。SDK 會自動寫入此欄位，以便未來版本能偵測並遷移較舊的格式；手動撰寫配置時可省略此欄位，SDK 會將該檔案視為目前版本。

聯邦設定檔範例

configs/production.json

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

如果省略 authentication.identity_token，SDK 會回退到環境中的 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN。

OAuth 範圍

您在聯邦規則上設定的 oauth_scope 決定了鑄造的存取權杖可以呼叫哪些 Claude API 端點。

範圍	授予存取權限
`workspace:developer`	規則工作區中所有非管理性的 Claude API 端點：Messages（包括串流和權杖計數）、Models、Managed Agents 及其工作階段、Files 和 Skills。這與為同一工作區簽發的 API 金鑰所擁有的存取權限相同。
`workspace:inference`	規則工作區中的推論端點：Messages（包括串流和權杖計數）、Models，以及 OpenAI 相容的聊天端點。適用於只需要呼叫 Claude 而永遠不需要管理 Files、Skills 或其他資源的工作負載。
`workspace:manage_tunnels`	MCP 通道 API：建立、列出和取得通道，註冊和封存 CA 憑證，顯示和輪替通道權杖，以及封存通道。當您從 Console 的建立通道對話視窗建立規則時，該視窗會鎖定此範圍。
`org:admin`	對 Admin API 的完整存取權限（組織成員、邀請、工作區、API 金鑰等）。OAuth `org:admin` 權杖只能建立或修改範圍為 `workspace:developer` 或 `workspace:inference` 的規則，且無法更新支援任何其他範圍規則的簽發者；請參閱限制。

對權杖範圍之外的端點發出的請求會回傳 HTTP 403。目前不提供更細緻的範圍（按資源，或讀取與寫入區分）。

權限邊界

聯邦規則的 oauth_scope 是上限：鑄造的權杖永遠不能超過它。目標服務帳戶的 organization_role（developer 或 admin）決定了哪些範圍可以被授予，因此授予 org:admin 的規則必須以 organization_role=admin 的服務帳戶為目標。有效權限是規則範圍與服務帳戶角色的交集。

規則 `oauth_scope`	服務帳戶 `organization_role`	有效權限
`workspace:developer`	`admin`	僅限規則工作區中的 Claude API 存取。範圍將權杖限制在角色之下。
`org:admin`	`admin`	完整的 Admin API 存取權限（組織成員、邀請、工作區、API 金鑰等），減去 OAuth 呼叫者的例外限制；請參閱限制。

驗證規則

當您建立或更新簽發者和規則，以及在交換時驗證傳入的 JWT 時，Anthropic 會強制執行這些限制。

如需完整的參數詳細資訊和回應結構，請參閱服務帳戶 API 參考、聯邦簽發者 API 參考和聯邦規則 API 參考。

資源欄位

欄位	限制
簽發者、規則和服務帳戶的 `name`	必須符合 `^[a-z0-9-]+$`，長度為 1 到 255 個字元。
`workspace_id`	除非 `applies_to_all_workspaces` 為 true，否則建立時為必填。其配額、計費和速率限制適用於在此規則下鑄造的權杖的工作區（`wrkspc_...`）。必須是同一組織中的工作區，且目標服務帳戶必須是該工作區的成員。
`applies_to_all_workspaces`	布林值。設為 `true` 可在組織中的每個工作區啟用該規則，而不是指定單一工作區；建立時必須提供此欄位或 `workspace_id` 其中之一。
`token_lifetime_seconds`	介於 `60` 和 `86400` 之間的整數（1 分鐘到 24 小時）。預設為 `3600`。超出此範圍的值會在請求時被拒絕。請參閱權杖生命週期與重新整理。

URL 欄位

issuer_url、jwks.discovery_base 和 jwks.url 欄位會經過驗證：

限制	詳細資訊
協定	必須是 `https`。
連接埠	必須是 `443`（明確指定或預設）。
主機	必須是您的 OIDC 提供者的公開 DNS 主機名稱。必須解析為公開 IP 位址；不接受 IP 字面值。

URL 驗證失敗會回傳 400 invalid_request_error，並在錯誤訊息前加上欄位名稱作為前綴（例如 issuer_url: url must use https scheme）。

URL 限制僅適用於 Anthropic 會撥接的 URL。在 explicit_url 和 inline JWKS 模式下，以及在設定了 jwks.discovery_base 的 discovery 模式下，issuer_url 僅作為字串與 JWT iss 宣告進行比較，永遠不會被擷取，因此它可以參照內部主機名稱或非標準連接埠。

JWT 驗證

限制	詳細資訊
最大大小	`assertion` JWT 最多為 16 KiB。
簽章演算法	僅接受非對稱演算法（RSA 和 ECDSA 系列：ES256、ES384、ES512、RS256、RS384、RS512、PS256、PS384、PS512）。HMAC（`HS256`、`HS384`、`HS512`）和 `none` 會被拒絕。
金鑰 ID	JWT 標頭必須帶有與簽發者 JWKS 中某個金鑰相符的 `kid`。沒有 `kid` 的權杖會被拒絕。
必要宣告	`sub` 必須存在。`iat` 必須存在且不在未來。`exp` 必須存在且在未來。
最大生命週期	權杖的生命週期（`exp` 減去 `iat`）不得超過簽發者配置的最大值（預設為 1 小時，可在 Claude Console 中為每個簽發者配置）。
時鐘偏差	對 `exp`、`nbf` 和 `iat` 套用 30 秒的寬限。

規則匹配語意

聯邦規則的 match 區塊決定是否接受傳入的 JWT。所有已填入的欄位都以 AND 語意進行評估：JWT 必須滿足每個已填入的匹配器。至少必須設定 subject_prefix、claims 或 condition 其中之一；僅包含 audience（或完全沒有匹配器）的 match 區塊會被拒絕。這可防止規則接受來自簽發者的所有權杖。

匹配器	類型	語意
`subject_prefix`	string	與 JWT `sub` 宣告進行精確匹配。結尾的 `` 使其成為前綴匹配（`sub` 值必須以 `` 之前的字元開頭）。區分大小寫。
`audience`	string	JWT `aud` 宣告必須包含此精確字串。當 `aud` 是陣列時，任何精確匹配的元素都能滿足檢查。
`claims`	map<string, string>	每個鍵是頂層宣告名稱，每個值是所需的精確字串值。對於巢狀、數值、布林或複雜的宣告（如清單和映射），請改用帶有 CEL 運算式的 `condition`。
`condition`	string (CEL)	必須評估為 `true` 的 CEL 運算式。

CEL 評估環境

condition 運算式可存取單一變數：

變數	類型	內容
`claims`	map	完整解碼的 JWT 宣告集。巢狀物件可作為巢狀映射存取。

範例：

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

CEL 條件是安全邊界。對超出預期的輸入評估為 true 的運算式會授予超出預期的存取權限。當靜態匹配器能表達您的限制時，請優先使用它們。

錯誤

權杖交換錯誤

POST /v1/oauth/token 以標準的 API 錯誤格式回傳錯誤。SDK 會將交換失敗包裝在型別化的 FederationExchangeError（或對應語言的等效類別）中，該類別會公開 HTTP 狀態、回應主體和 request_id。

狀態	錯誤	原因	解決方法
400	`invalid_request`	`federation_rule_id` 格式錯誤或缺少必要的請求欄位。	驗證 `fdrl_` ID 以及請求主體是否包含所有必要欄位。
400	`invalid_request`	`workspace_id_required`：聯邦規則在多個工作區啟用，而請求省略了 `workspace_id`。	將 `ANTHROPIC_WORKSPACE_ID`（或原始請求上的 `workspace_id` 主體欄位）設定為您希望權杖限定範圍的 `wrkspc_...` ID。請參閱權杖交換請求。
400	`invalid_grant`	JWT `iss` 宣告與註冊的 `issuer_url` 不完全相等。	逐位元組比較，包括結尾斜線和協定：`jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`。
400	`invalid_grant`	JWKS 擷取失敗、JWKS 過時，或 JWT 是以不在 JWKS 中的金鑰簽署的。	對於 `inline` 模式，請使用輪替後的金鑰更新簽發者。對於 `discovery` 和 `explicit_url`，請確認 JWKS 端點可透過連接埠 443 存取；如果簽發者最近輪替了其簽署金鑰，請參閱金鑰輪替與快取。
400	`invalid_grant`	JWT `exp` 宣告已過期（超出 30 秒的偏差視窗）。	確認您的身分提供者正在投射新的權杖，且 SDK 正在重新讀取權杖檔案。
400	`invalid_grant`	JWT 已通過驗證，但其宣告不滿足規則的 `match` 區塊。	解碼 JWT 並將每個宣告與規則進行比較。`subject_prefix` 區分大小寫。`audience` 需要精確的元素匹配。
400	`invalid_grant`	`federation_rule_id` 不存在、已封存，或 JWT 未獲授權使用它（為防止列舉而合併處理）。	在 Claude Console 中確認規則 ID，並確認規則尚未被封存。

所有 invalid_grant 失敗都會回傳 HTTP 400；具體原因僅記錄在伺服器端，不會在回應中公開。

常見的 SDK 端失敗

症狀	原因	解決方法
SDK 回報「no credentials」而非進行交換	`ANTHROPIC_FEDERATION_RULE_ID`、`ANTHROPIC_ORGANIZATION_ID`、`ANTHROPIC_SERVICE_ACCOUNT_ID` 或 `ANTHROPIC_IDENTITY_TOKEN[_FILE]` 其中之一未設定，且沒有作用中的設定檔。	設定所有四個變數，或配置一個設定檔。
SDK 使用 API 金鑰驗證而非聯邦	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 已設定且優先順序較高。	取消設定金鑰或權杖變數。
第一次請求時出現 `FileNotFoundError`	`ANTHROPIC_IDENTITY_TOKEN_FILE` 中的路徑不存在。SDK 在交換時才延遲開啟檔案。	確認投射權杖的磁碟區已掛載且路徑相符。
權杖交換成功，但 Claude API 請求回傳 403	鑄造的權杖範圍未授予對該端點的存取權限。	對照 OAuth 範圍檢查規則的 `oauth_scope`。
驗證因空憑證而失敗	憑證環境變數已匯出但設定為空字串。空值仍會佔據其優先順序位置。	使用 `unset VAR` 取消設定變數，而不是 `VAR=""`。

疑難排解失敗的交換

400 invalid_grant 回應是刻意不透明的；具體原因僅記錄在伺服器端。

請先從 Claude Console 中的驗證歷史頁面開始。最近的交換嘗試會顯示被評估的簽發者和規則、被檢查的 JWT 宣告，以及哪個驗證步驟失敗，這通常可以省去以下的檢查步驟。

如果您仍需要從 JWT 本身進行除錯，請依序執行以下檢查：

解碼 JWT
解碼您傳送的 assertion，以便將每個宣告與您的簽發者和規則配置進行比較：
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
檢查 iss 是否與簽發者相符
解碼後的 iss 宣告必須與註冊的 issuer_url 逐位元組相等，包括協定、連接埠和任何結尾斜線。單一字元的不符就會導致驗證失敗。
檢查 aud 是否與規則相符
解碼後的 aud 宣告必須包含與規則的 audience 值完全相符的項目。當 aud 是陣列時，必須有一個元素完全相符。
檢查 sub 和每個 claims 項目
將 sub 與規則的 subject_prefix 進行比較（區分大小寫；結尾的 * 為前綴匹配，其他情況為精確匹配）。將規則的 claims 映射中的每個鍵與同名的頂層宣告進行比較。
檢查 exp、nbf 和 iat
exp 必須在未來，nbf/iat 必須在過去，且在 30 秒的偏差視窗內。如果工作負載主機的時鐘發生漂移，原本有效的權杖也會被拒絕。
檢查 JWKS 可達性
對於 discovery 模式，透過公開 HTTPS 在連接埠 443 上擷取 <jwks.discovery_base or issuer_url>/.well-known/openid-configuration，並確認 jwks_uri 可解析。對於 explicit_url，直接擷取 JWKS URL。對於 inline，確認簽發者的簽署金鑰自您註冊金鑰以來沒有輪替過。
如果簽發者輪替了其簽署金鑰並立即開始使用它簽署，在 Anthropic 的 JWKS 快取重新整理期間，交換可能會失敗長達一分鐘。請參閱金鑰輪替與快取。

JWKS 來源模式

當您註冊聯邦簽發者時，jwks 欄位控制 Anthropic 如何取得用於驗證該簽發者 JWT 簽章的公開金鑰。它是以 type 為鍵的可辨識聯集（discriminated union）：

`jwks.type`	`jwks` 結構	行為	使用時機
`discovery`（預設）	`{ "type": "discovery", "discovery_base": "https://..." }`（`discovery_base` 為選填；當探索 URL 與 `issuer_url` 不同時設定）	Anthropic 擷取 `<discovery_base or issuer_url>/.well-known/openid-configuration`，從探索文件中讀取 `jwks_uri`，並從該處擷取 JWKS。	您的 IdP 在公開網際網路上提供標準的 OIDC 探索文件。大多數受管理的提供者（EKS、GKE、Cloud Run、GitHub Actions、Entra ID）都支援此模式。
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic 直接從 `url` 擷取 JWKS。`issuer_url` 僅用於與 JWT `iss` 宣告進行字串比較，永遠不會被撥接。	您的 IdP 不提供探索文件，或探索僅限內部使用但 JWKS 可公開存取。
`inline`	`{ "type": "inline", "keys": [...] }`	您以內嵌方式提供 JWK 物件陣列（JWKS 文件中的 `keys` 陣列，而非包裝物件）。Anthropic 不會發出任何對外請求。`issuer_url` 僅用於 `iss` 比較。	隔離（air-gapped）環境、具有叢集內部簽發者 URL 的自行管理 Kubernetes 叢集，或當您想要明確控制金鑰輪替時。

可辨識聯集在結構上使伴隨欄位互斥。discovery 和 explicit_url 也都接受選填的 ca_cert_pem 字串，供使用私有 CA 提供 TLS 的簽發者使用。

金鑰輪替與快取

在 discovery 和 explicit_url 模式下，Anthropic 會快取擷取到的 JWKS。如果您的身分提供者發佈了新的簽署金鑰並立即開始使用它簽署權杖，在快取重新整理期間，出示這些權杖的交換可能會因簽章錯誤而失敗長達 1 分鐘。

為避免此時間窗口，請在您的身分提供者開始使用新簽署金鑰簽署權杖之前至少 15 分鐘，先在 JWKS 中發佈該金鑰，並將被取代的金鑰保留在 JWKS 中，直到它簽署的權杖全部過期。受管理的身分提供者通常會自行遵循此規範。如果您自行營運簽發者（自行管理的 Kubernetes 叢集、SPIRE OIDC 探索提供者，或配置了輪替週期的 Okta 自訂授權伺服器），請確認您的輪替政策會在首次使用之前發佈新金鑰。

在 inline 模式下沒有自動金鑰重新整理。當您的身分提供者輪替其簽署金鑰時，您必須使用新的 JWKS 更新簽發者配置，否則所有權杖交換都會在簽章驗證時失敗。

Was this page helpful?

管理驗證

WIF 參考

Workload Identity Federation 的環境變數、驗證規則、設定檔配置與錯誤參考。

本頁彙整了 Workload Identity Federation 的配置介面、驗證限制與錯誤對應。如需設定逐步說明，請參閱身分提供者指南。

權杖交換請求

欄位	必填	說明
`grant_type`	是	一律為 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	是	由您的身分提供者簽發的 OIDC JWT。
`federation_rule_id`	是	要評估的聯邦規則的標記 ID（`fdrl_...`）。
`organization_id`	是	您的 Anthropic 組織的 UUID。
`service_account_id`	是	目標服務帳戶的標記 ID（`svac_...`）。
`workspace_id`	視情況而定	要將鑄造的權杖限定範圍的工作區標記 ID（`wrkspc_...`），或使用字面值 `default` 代表組織的預設工作區。當規則在多個工作區啟用時為必填。省略時，伺服器會選擇該規則唯一啟用的工作區。

權杖交換回應

POST /v1/oauth/token 回傳標準的 OAuth 2.0 權杖回應（RFC 6749 §5.1）：

欄位	類型	說明
`access_token`	string	短效的 Anthropic 權杖，前綴為 `sk-ant-oat01-...`。以 `Authorization: Bearer <token>` 形式傳遞。
`token_type`	string	一律為 `Bearer`。
`expires_in`	integer	權杖到期前的秒數。
`scope`	string	由匹配規則授予的 OAuth 範圍。

環境變數

SDK 會讀取這些變數，以在不需建構函式引數的情況下執行聯邦權杖交換。

變數	必填	說明	範例
`ANTHROPIC_FEDERATION_RULE_ID`	是	要評估的聯邦規則的標記 ID。	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	是	您的 Anthropic 組織的 UUID。可在 Claude Console 的 Settings > Organization 中找到。	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	由您的「identity provider」（身分提供者），即 IdP 簽發的 JWT 的檔案系統路徑。SDK 在每次交換時都會重新讀取此檔案，以確保在磁碟上輪替的投射權杖始終是最新的。	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	以字串形式表示的 JWT 字面值。當您的平台以環境變數而非檔案的方式注入權杖時使用。	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	是	簽發的存取權杖所代表的目標 Anthropic 服務帳戶的標記 ID。	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	視情況而定	要將鑄造的權杖限定範圍的工作區標記 ID，或使用字面值 `default`。當聯邦規則在多個工作區啟用時為必填；當規則綁定到單一工作區時為選填。鑄造的權杖在交換時即限定於此工作區，因此切換工作區需要進行新的交換。	`wrkspc_...`
`ANTHROPIC_PROFILE`	否	要載入的配置設定檔名稱。優先於本表中的聯邦環境變數。	`staging-profile`

憑證優先順序

SDK 依此順序解析憑證。第一個產生憑證的來源勝出。

順序	來源	備註
1	建構函式引數（`api_key=`、`auth_token=`、`credentials=`）	一律覆蓋其他所有來源。
2	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`	完全遮蔽聯邦。從 API 金鑰遷移時請取消設定這些變數。
3	`ANTHROPIC_PROFILE`	載入 `<config_dir>/configs/<name>.json`。指定名稱的設定檔不存在時會產生錯誤，而非繼續往下嘗試。
4	聯邦環境變數	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`。
5	作用中設定檔	從 `<config_dir>/active_config` 解析，若無則回退到名為 `default` 的設定檔。

設定檔配置檔案

設定檔是 SDK 和 ant CLI 都會讀取的具名配置檔案。設定檔讓您可以將聯邦參數隨容器映像一起發佈，或在不更改程式碼的情況下切換環境。

配置目錄

SDK 依此順序尋找配置目錄：

$ANTHROPIC_CONFIG_DIR
Linux 和 macOS 上的 ~/.config/anthropic
Windows 上的 %APPDATA%\Anthropic

作用中設定檔

作用中設定檔名稱依此順序解析：

$ANTHROPIC_PROFILE
<config_dir>/active_config 的內容（由 ant profile activate <name> 寫入的單行檔案）
字面名稱 default

Claude Code 和 Claude Agent SDK 遵循相同的解析順序，因此在此配置的聯邦設定檔也能在無需額外設定的情況下為這些工具進行驗證。

檔案配置

路徑	內容	敏感性
`<config_dir>/configs/<profile>.json`	`version`、`authentication` 區塊、`organization_id`、`workspace_id` 和 `base_url`。	非機密。可安全提交或烘焙到映像中。
`<config_dir>/credentials/<profile>.json`	`version`、快取的 `access_token`、`expires_at`，以及（互動式登入時的）`refresh_token`。	機密。由 SDK 以 `0600` 模式寫入。

聯邦設定檔範例

configs/production.json

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

如果省略 authentication.identity_token，SDK 會回退到環境中的 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN。

OAuth 範圍

您在聯邦規則上設定的 oauth_scope 決定了鑄造的存取權杖可以呼叫哪些 Claude API 端點。

範圍	授予存取權限
`workspace:developer`	規則工作區中所有非管理性的 Claude API 端點：Messages（包括串流和權杖計數）、Models、Managed Agents 及其工作階段、Files 和 Skills。這與為同一工作區簽發的 API 金鑰所擁有的存取權限相同。
`workspace:inference`	規則工作區中的推論端點：Messages（包括串流和權杖計數）、Models，以及 OpenAI 相容的聊天端點。適用於只需要呼叫 Claude 而永遠不需要管理 Files、Skills 或其他資源的工作負載。
`workspace:manage_tunnels`	MCP 通道 API：建立、列出和取得通道，註冊和封存 CA 憑證，顯示和輪替通道權杖，以及封存通道。當您從 Console 的建立通道對話視窗建立規則時，該視窗會鎖定此範圍。
`org:admin`	對 Admin API 的完整存取權限（組織成員、邀請、工作區、API 金鑰等）。OAuth `org:admin` 權杖只能建立或修改範圍為 `workspace:developer` 或 `workspace:inference` 的規則，且無法更新支援任何其他範圍規則的簽發者；請參閱限制。

對權杖範圍之外的端點發出的請求會回傳 HTTP 403。目前不提供更細緻的範圍（按資源，或讀取與寫入區分）。

權限邊界

規則 `oauth_scope`	服務帳戶 `organization_role`	有效權限
`workspace:developer`	`admin`	僅限規則工作區中的 Claude API 存取。範圍將權杖限制在角色之下。
`org:admin`	`admin`	完整的 Admin API 存取權限（組織成員、邀請、工作區、API 金鑰等），減去 OAuth 呼叫者的例外限制；請參閱限制。

驗證規則

當您建立或更新簽發者和規則，以及在交換時驗證傳入的 JWT 時，Anthropic 會強制執行這些限制。

如需完整的參數詳細資訊和回應結構，請參閱服務帳戶 API 參考、聯邦簽發者 API 參考和聯邦規則 API 參考。

資源欄位

欄位	限制
簽發者、規則和服務帳戶的 `name`	必須符合 `^[a-z0-9-]+$`，長度為 1 到 255 個字元。
`workspace_id`	除非 `applies_to_all_workspaces` 為 true，否則建立時為必填。其配額、計費和速率限制適用於在此規則下鑄造的權杖的工作區（`wrkspc_...`）。必須是同一組織中的工作區，且目標服務帳戶必須是該工作區的成員。
`applies_to_all_workspaces`	布林值。設為 `true` 可在組織中的每個工作區啟用該規則，而不是指定單一工作區；建立時必須提供此欄位或 `workspace_id` 其中之一。
`token_lifetime_seconds`	介於 `60` 和 `86400` 之間的整數（1 分鐘到 24 小時）。預設為 `3600`。超出此範圍的值會在請求時被拒絕。請參閱權杖生命週期與重新整理。

URL 欄位

issuer_url、jwks.discovery_base 和 jwks.url 欄位會經過驗證：

限制	詳細資訊
協定	必須是 `https`。
連接埠	必須是 `443`（明確指定或預設）。
主機	必須是您的 OIDC 提供者的公開 DNS 主機名稱。必須解析為公開 IP 位址；不接受 IP 字面值。

URL 驗證失敗會回傳 400 invalid_request_error，並在錯誤訊息前加上欄位名稱作為前綴（例如 issuer_url: url must use https scheme）。

JWT 驗證

限制	詳細資訊
最大大小	`assertion` JWT 最多為 16 KiB。
簽章演算法	僅接受非對稱演算法（RSA 和 ECDSA 系列：ES256、ES384、ES512、RS256、RS384、RS512、PS256、PS384、PS512）。HMAC（`HS256`、`HS384`、`HS512`）和 `none` 會被拒絕。
金鑰 ID	JWT 標頭必須帶有與簽發者 JWKS 中某個金鑰相符的 `kid`。沒有 `kid` 的權杖會被拒絕。
必要宣告	`sub` 必須存在。`iat` 必須存在且不在未來。`exp` 必須存在且在未來。
最大生命週期	權杖的生命週期（`exp` 減去 `iat`）不得超過簽發者配置的最大值（預設為 1 小時，可在 Claude Console 中為每個簽發者配置）。
時鐘偏差	對 `exp`、`nbf` 和 `iat` 套用 30 秒的寬限。

規則匹配語意

匹配器	類型	語意
`subject_prefix`	string	與 JWT `sub` 宣告進行精確匹配。結尾的 `` 使其成為前綴匹配（`sub` 值必須以 `` 之前的字元開頭）。區分大小寫。
`audience`	string	JWT `aud` 宣告必須包含此精確字串。當 `aud` 是陣列時，任何精確匹配的元素都能滿足檢查。
`claims`	map<string, string>	每個鍵是頂層宣告名稱，每個值是所需的精確字串值。對於巢狀、數值、布林或複雜的宣告（如清單和映射），請改用帶有 CEL 運算式的 `condition`。
`condition`	string (CEL)	必須評估為 `true` 的 CEL 運算式。

CEL 評估環境

condition 運算式可存取單一變數：

變數	類型	內容
`claims`	map	完整解碼的 JWT 宣告集。巢狀物件可作為巢狀映射存取。

範例：

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

CEL 條件是安全邊界。對超出預期的輸入評估為 true 的運算式會授予超出預期的存取權限。當靜態匹配器能表達您的限制時，請優先使用它們。

錯誤

權杖交換錯誤

狀態	錯誤	原因	解決方法
400	`invalid_request`	`federation_rule_id` 格式錯誤或缺少必要的請求欄位。	驗證 `fdrl_` ID 以及請求主體是否包含所有必要欄位。
400	`invalid_request`	`workspace_id_required`：聯邦規則在多個工作區啟用，而請求省略了 `workspace_id`。	將 `ANTHROPIC_WORKSPACE_ID`（或原始請求上的 `workspace_id` 主體欄位）設定為您希望權杖限定範圍的 `wrkspc_...` ID。請參閱權杖交換請求。
400	`invalid_grant`	JWT `iss` 宣告與註冊的 `issuer_url` 不完全相等。	逐位元組比較，包括結尾斜線和協定：`jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`。
400	`invalid_grant`	JWKS 擷取失敗、JWKS 過時，或 JWT 是以不在 JWKS 中的金鑰簽署的。	對於 `inline` 模式，請使用輪替後的金鑰更新簽發者。對於 `discovery` 和 `explicit_url`，請確認 JWKS 端點可透過連接埠 443 存取；如果簽發者最近輪替了其簽署金鑰，請參閱金鑰輪替與快取。
400	`invalid_grant`	JWT `exp` 宣告已過期（超出 30 秒的偏差視窗）。	確認您的身分提供者正在投射新的權杖，且 SDK 正在重新讀取權杖檔案。
400	`invalid_grant`	JWT 已通過驗證，但其宣告不滿足規則的 `match` 區塊。	解碼 JWT 並將每個宣告與規則進行比較。`subject_prefix` 區分大小寫。`audience` 需要精確的元素匹配。
400	`invalid_grant`	`federation_rule_id` 不存在、已封存，或 JWT 未獲授權使用它（為防止列舉而合併處理）。	在 Claude Console 中確認規則 ID，並確認規則尚未被封存。

所有 invalid_grant 失敗都會回傳 HTTP 400；具體原因僅記錄在伺服器端，不會在回應中公開。

常見的 SDK 端失敗

症狀	原因	解決方法
SDK 回報「no credentials」而非進行交換	`ANTHROPIC_FEDERATION_RULE_ID`、`ANTHROPIC_ORGANIZATION_ID`、`ANTHROPIC_SERVICE_ACCOUNT_ID` 或 `ANTHROPIC_IDENTITY_TOKEN[_FILE]` 其中之一未設定，且沒有作用中的設定檔。	設定所有四個變數，或配置一個設定檔。
SDK 使用 API 金鑰驗證而非聯邦	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 已設定且優先順序較高。	取消設定金鑰或權杖變數。
第一次請求時出現 `FileNotFoundError`	`ANTHROPIC_IDENTITY_TOKEN_FILE` 中的路徑不存在。SDK 在交換時才延遲開啟檔案。	確認投射權杖的磁碟區已掛載且路徑相符。
權杖交換成功，但 Claude API 請求回傳 403	鑄造的權杖範圍未授予對該端點的存取權限。	對照 OAuth 範圍檢查規則的 `oauth_scope`。
驗證因空憑證而失敗	憑證環境變數已匯出但設定為空字串。空值仍會佔據其優先順序位置。	使用 `unset VAR` 取消設定變數，而不是 `VAR=""`。

疑難排解失敗的交換

400 invalid_grant 回應是刻意不透明的；具體原因僅記錄在伺服器端。

如果您仍需要從 JWT 本身進行除錯，請依序執行以下檢查：

解碼 JWT
解碼您傳送的 assertion，以便將每個宣告與您的簽發者和規則配置進行比較：
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
檢查 iss 是否與簽發者相符
解碼後的 iss 宣告必須與註冊的 issuer_url 逐位元組相等，包括協定、連接埠和任何結尾斜線。單一字元的不符就會導致驗證失敗。
檢查 aud 是否與規則相符
解碼後的 aud 宣告必須包含與規則的 audience 值完全相符的項目。當 aud 是陣列時，必須有一個元素完全相符。
檢查 sub 和每個 claims 項目
將 sub 與規則的 subject_prefix 進行比較（區分大小寫；結尾的 * 為前綴匹配，其他情況為精確匹配）。將規則的 claims 映射中的每個鍵與同名的頂層宣告進行比較。
檢查 exp、nbf 和 iat
exp 必須在未來，nbf/iat 必須在過去，且在 30 秒的偏差視窗內。如果工作負載主機的時鐘發生漂移，原本有效的權杖也會被拒絕。
檢查 JWKS 可達性
對於 discovery 模式，透過公開 HTTPS 在連接埠 443 上擷取 <jwks.discovery_base or issuer_url>/.well-known/openid-configuration，並確認 jwks_uri 可解析。對於 explicit_url，直接擷取 JWKS URL。對於 inline，確認簽發者的簽署金鑰自您註冊金鑰以來沒有輪替過。
如果簽發者輪替了其簽署金鑰並立即開始使用它簽署，在 Anthropic 的 JWKS 快取重新整理期間，交換可能會失敗長達一分鐘。請參閱金鑰輪替與快取。

JWKS 來源模式

當您註冊聯邦簽發者時，jwks 欄位控制 Anthropic 如何取得用於驗證該簽發者 JWT 簽章的公開金鑰。它是以 type 為鍵的可辨識聯集（discriminated union）：

`jwks.type`	`jwks` 結構	行為	使用時機
`discovery`（預設）	`{ "type": "discovery", "discovery_base": "https://..." }`（`discovery_base` 為選填；當探索 URL 與 `issuer_url` 不同時設定）	Anthropic 擷取 `<discovery_base or issuer_url>/.well-known/openid-configuration`，從探索文件中讀取 `jwks_uri`，並從該處擷取 JWKS。	您的 IdP 在公開網際網路上提供標準的 OIDC 探索文件。大多數受管理的提供者（EKS、GKE、Cloud Run、GitHub Actions、Entra ID）都支援此模式。
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic 直接從 `url` 擷取 JWKS。`issuer_url` 僅用於與 JWT `iss` 宣告進行字串比較，永遠不會被撥接。	您的 IdP 不提供探索文件，或探索僅限內部使用但 JWKS 可公開存取。
`inline`	`{ "type": "inline", "keys": [...] }`	您以內嵌方式提供 JWK 物件陣列（JWKS 文件中的 `keys` 陣列，而非包裝物件）。Anthropic 不會發出任何對外請求。`issuer_url` 僅用於 `iss` 比較。	隔離（air-gapped）環境、具有叢集內部簽發者 URL 的自行管理 Kubernetes 叢集，或當您想要明確控制金鑰輪替時。

可辨識聯集在結構上使伴隨欄位互斥。discovery 和 explicit_url 也都接受選填的 ca_cert_pem 字串，供使用私有 CA 提供 TLS 的簽發者使用。

金鑰輪替與快取

Was this page helpful?

權杖交換請求

權杖交換回應

環境變數

憑證優先順序

設定檔配置檔案

配置目錄

作用中設定檔

檔案配置

聯邦設定檔範例

OAuth 範圍

權限邊界

驗證規則

資源欄位

URL 欄位

JWT 驗證

規則匹配語意

CEL 評估環境

錯誤

權杖交換錯誤

常見的 SDK 端失敗

疑難排解失敗的交換

JWKS 來源模式

金鑰輪替與快取

權杖交換請求

權杖交換回應

環境變數

憑證優先順序

設定檔配置檔案

配置目錄

作用中設定檔

檔案配置

聯邦設定檔範例

OAuth 範圍

權限邊界

驗證規則

資源欄位

URL 欄位

JWT 驗證

規則匹配語意

CEL 評估環境

錯誤

權杖交換錯誤

常見的 SDK 端失敗

疑難排解失敗的交換

JWKS 來源模式

金鑰輪替與快取

權杖交換請求

權杖交換回應

環境變數

憑證優先順序

設定檔配置檔案

配置目錄

作用中設定檔

檔案配置

聯邦設定檔範例

OAuth 範圍

權限邊界

驗證規則

資源欄位

URL 欄位

JWT 驗證

規則匹配語意

CEL 評估環境

錯誤

權杖交換錯誤

常見的 SDK 端失敗

疑難排解失敗的交換

JWKS 來源模式

金鑰輪替與快取

權杖交換請求

權杖交換回應

環境變數

憑證優先順序

設定檔配置檔案

配置目錄

作用中設定檔

檔案配置

聯邦設定檔範例

OAuth 範圍

權限邊界

驗證規則

資源欄位

URL 欄位

JWT 驗證

規則匹配語意

CEL 評估環境

錯誤

權杖交換錯誤

常見的 SDK 端失敗

疑難排解失敗的交換

JWKS 來源模式

金鑰輪替與快取