身份驗證

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 中，前往 API keys 頁面（platform.claude.com/settings/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 金鑰儲存在密鑰管理工具中、定期輪替，並停用或刪除任何您懷疑已外洩的金鑰。在 Claude Console 的 API keys 頁面上，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 的 Workspaces 頁面（platform.claude.com/settings/workspaces）的 ID 欄位中找到工作區的 ID，或呼叫 List Workspaces 端點取得。List Workspaces 僅在您傳入 include_default=true 時才會包含預設工作區；其 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": "This API key is not scoped to a workspace, so this request must include the anthropic-workspace-id header with the ID of the workspace to use. Add the header, or use an API key that is scoped to a workspace."
  },
  "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 keys 頁面建立 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 的詳細資訊，請參閱 WIF 參考資料，相較於長期金鑰，建議優先使用此方式。

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

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

Workload Identity Federation

Workload Identity Federation（WIF）可讓工作負載使用由您已信任的「identity provider」（身分提供者），即 IdP，所核發的短期身分權杖進行驗證。這類 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 會向該裝置核發一個短期存取權杖，並將用量計費至您的工作區。權杖的範圍限定於您的工作區，會在 1 小時後到期，且僅授權 Messages API 呼叫。

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

後續步驟