身份驗證

Claude API 支援三種驗證請求的方式：

API 金鑰和 Workload Identity Federation 授予對 Claude API 端點的相同存取權限。選擇 API 金鑰可快速上手：用於您自己開發的個人金鑰，或用於任何共享用途的服務帳戶金鑰。當您的工作負載已經擁有可以聯合的平台發行身份時，請改用 Workload Identity Federation。對於您分發給終端使用者的 iOS 和 macOS 應用程式，請使用 App Attest。

API 金鑰

API 金鑰是您在 Claude Console 中生成的靜態密鑰，並在每個請求中作為 bearer token 在 Authorization 標頭中發送。

金鑰類型

當您建立金鑰時，您會選擇其類型，這決定了金鑰可以做什麼、在哪裡運作，以及何時停止運作：

個人金鑰和服務帳戶金鑰是身份支援的：每個金鑰都屬於您的組織已經管理的使用者或服務帳戶，且每個請求都以該身份行事。當該身份從組織中被移除時，金鑰就會停止運作。這意味著金鑰不會意外地比擁有它們的人員或工作負載存活更久。對於新的整合，請優先使用它們而非工作區金鑰。

使用個人金鑰進行您自己的開發和腳本。共享的個人金鑰作為一個人行事，並在該人離開時失效。對於共享或自動化的工作負載（CI、生產服務），請讓組織管理員建立服務帳戶，以便工作負載擁有自己的身份。

工作區 API 金鑰仍然可以運作，但應被視為舊版；身份支援的金鑰或 Workload Identity Federation 是首選。要遷移，請參閱替換工作區 API 金鑰。

建立和使用金鑰

• 建立金鑰： 前往 Claude Console 中的 Settings → API keys 並點擊 Create key。為金鑰命名並選擇過期時間。將 Linked account 設定為您自己以建立個人金鑰，或設定為服務帳戶以建立跨多個使用者共享的金鑰。您也可以將金鑰範圍限定於特定工作區，這讓您在未來的請求中可以跳過手動設定工作區 ID。
• 使用金鑰： 在直接 HTTP 請求中將其作為 Authorization: Bearer <key> 發送，或設定 ANTHROPIC_API_KEY 環境變數，用戶端 SDK 會自動取用它。

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

舊版的 x-api-key: YOUR_API_KEY 標頭仍然支援用於替代 Authorization。

請將 API 金鑰儲存在密鑰管理器中、定期輪換，並停用或刪除任何您懷疑已洩漏的金鑰。在 API 金鑰頁面上，Disable 是可逆的（Admin API 會將金鑰的 status 回報為 "inactive"，而 Re-enable 會將其恢復為 "active"），而 Delete 則是永久性的：金鑰會被封存，並仍會以 status: "archived" 出現在 List API Keys 中。已過期的金鑰只能被刪除。您也可以在建立金鑰時設定過期時間，以限制洩漏憑證可被使用的時間長度。

client = Anthropic(api_key="my-anthropic-api-key")
# 或者，在環境中設定 ANTHROPIC_API_KEY 後：
client = Anthropic()

選擇工作區

為特定工作區建立的 API 金鑰僅在該工作區中運作，使用這些金鑰的 API 請求可以省略工作區 ID。

如果您的 API 金鑰未限定於某個工作區，您必須在每個請求的 anthropic-workspace-id 標頭中指定工作區 ID。請參閱以下範例，了解如何在請求或 SDK 中設定此標頭。

Admin API 僅在金鑰未限定於特定工作區時才接受個人金鑰或服務帳戶金鑰。

您可以在 Claude Console 中 Settings → Workspaces 的 ID 欄位找到工作區的 ID，或呼叫 List Workspaces 端點取得。只有在您傳入 include_default=true 時，List Workspaces 才會包含預設工作區；其 ID 也會出現在任何於該工作區執行之請求的 anthropic-workspace-id 回應標頭中。

client = Anthropic()  # reads ANTHROPIC_API_KEY

# 多工作區金鑰的每個請求都必須提供。
# 單一工作區金鑰請省略 extra_headers。
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# 或者為此用戶端的每個請求設定一次：
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

如果使用未限定於工作區的金鑰發出的請求省略了標頭，API 會回傳 400 invalid_request_error：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

不是有效工作區 ID 的標頭值會回傳 400 invalid_request_error，訊息為 anthropic-workspace-id header must be a valid workspace ID.。如果工作區不存在，或金鑰的使用者或服務帳戶無權存取它，API 會回傳 404 not_found_error，訊息為 Workspace `<id>` not found.，與任何未知工作區的回應相同。

Workload Identity Federation 改為在令牌交換時選擇工作區；詳情請參閱 WIF 參考。

金鑰過期

當您從 Claude Console 中的 API 金鑰頁面建立 API 金鑰時，您會選擇過期時間：預設值（3 小時、1 天、7 天或 30 天）、自訂持續時間，或對於您儲存在密鑰管理器中並自行輪換的金鑰選擇 Never。如果您的組織有最大過期政策，Console 會將預設值和自訂持續時間限制為政策最大值，且 Never 不可用。現有金鑰保持其當前行為；過期時間在建立時設定，之後無法更改。當您在 Claude Console 中建立 Admin API 金鑰時，適用相同的過期選擇。

Anthropic 會在過期臨近時向金鑰的建立者發送電子郵件：對於生命週期至少 14 天的金鑰，在過期前 7 天發送；對於生命週期至少 7 天的金鑰，在過期前 1 天發送。生命週期較短的金鑰會在沒有警告電子郵件的情況下過期。

金鑰過期後，使用它發出的請求會回傳 401 authentication_error。建立新金鑰以恢復存取；過期的金鑰無法重新啟用。

Console 的 API 金鑰表格會顯示每個金鑰的過期時間，而 Admin API 會在 List API Keys 和 Retrieve API Key 端點上回報每個金鑰的 expires_at 時間戳記，讓您可以在金鑰過期前進行稽核和輪換。對於沒有過期時間的金鑰，此欄位為 null。

過期時間限制了洩漏憑證的生命週期，但它不能替代密鑰衛生。無論過期時間如何，都應將金鑰儲存在密鑰管理器中，並停用或刪除任何您懷疑已洩漏的金鑰。

替換工作區 API 金鑰

如果您有工作區金鑰，您可能想用 Workload Identity Federation 或個人或服務帳戶金鑰來替換它。這提供了更好的安全性和可觀察性。

有關配置 Workload Identity Federation 的詳情，請參閱 Workload Identity Federation，它比長期金鑰更受青睞。

要用個人或服務帳戶金鑰替換工作區金鑰：

1. 決定金鑰類型。 您自己的工具應使用個人金鑰。共享或無人值守的工作負載應使用服務帳戶金鑰。
2. 建立服務帳戶（如有必要）。您可能需要請組織管理員在 Settings → Service accounts 中建立一個，並將其加入相關工作區。
3. 建立新金鑰。 除非需要多個工作區，否則專門為整合的工作區建立它。
4. 部署新金鑰。 在整合讀取它的任何地方替換舊金鑰，通常是 ANTHROPIC_API_KEY 環境變數或密鑰管理器條目。對於多工作區金鑰，還需如選擇工作區所示發送 anthropic-workspace-id 標頭。
5. 刪除舊金鑰。 確認請求成功，然後在 API 金鑰頁面上刪除工作區金鑰。

Workload Identity Federation

Workload Identity Federation (WIF) 讓工作負載使用由您已經信任的身份提供者（IdP）發行的短期身份令牌進行身份驗證，例如 AWS IAM、Google Cloud 或任何符合標準的 OIDC 發行者（例如 GitHub Actions、Kubernetes 服務帳戶、SPIFFE、Microsoft Entra ID 或 Okta）。工作負載在 POST /v1/oauth/token 用其 IdP 發行的 JWT 交換短期 Claude API 存取令牌，SDK 會在令牌過期前自動刷新它。沒有需要鑄造、分發或輪換的 sk-ant-api... 字串。

聯合從您的環境中移除了長期的 Claude API 金鑰，這縮小了洩漏憑證的影響範圍，並讓您能使用與雲端資源相同的 IdP 控制來管理存取。它本身並不保證端到端的安全性：信任鏈的強度僅取決於您身份提供者的配置，而上游一跳的長期密鑰（例如，可以鑄造 IdP 令牌的靜態雲端憑證）仍可能破壞它。將聯合與您提供者的控制搭配使用，例如 IP 允許清單、MFA 和稽核日誌。

要配置聯合，您需要在 Claude Console 中建立三個資源（服務帳戶、聯合發行者和聯合規則），然後將您的 SDK 指向該規則。有關完整的設定演練，請參閱 Workload Identity Federation。

App Attest

App Attest 驗證直接從裝置呼叫 Claude API 的 iOS 和 macOS 應用程式。每個安裝都使用 Apple 的 App Attest 服務證明它是您在 Claude Console 中註冊的應用程式的真實、未修改的建置。然後 Anthropic 向裝置發行一個短期存取令牌，將使用量計費到您的工作區。令牌限定於您的工作區，一小時後過期，並僅授權 Messages API 呼叫。

要註冊您的應用程式並取得用戶端 ID，請參閱 iOS 和 macOS 應用程式的 App Attest。

後續步驟