身分驗證

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

API 金鑰與 Workload Identity Federation 對 Claude API 端點授予相同的存取權限。若要快速上手，請選擇 API 金鑰：個人金鑰用於您自己的開發，服務帳戶金鑰則用於任何共用的情境。當您的工作負載已具備可供聯合的平台簽發身分時，請改用 Workload Identity Federation。對於您發佈給終端使用者的 iOS 與 macOS 應用程式，請使用 App Attest。

API 金鑰

「API key」（API 金鑰）是您在 Claude Console 中產生的靜態密鑰，並在每個請求的 x-api-key 標頭中傳送。

金鑰類型

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

個人金鑰與服務帳戶金鑰是以身分為基礎的（identity-backed）：每把金鑰都屬於您的組織已在管理的某位使用者或服務帳戶，且每個請求都以該身分執行。當該身分被移出組織時，金鑰即停止運作。這表示金鑰不會意外地比擁有它的人員或工作負載存活得更久。對於新的整合，請優先使用它們而非工作區金鑰。

請將個人金鑰用於您自己的開發與腳本。共用的個人金鑰代表單一個人，當此人離開時便會失效。對於共用或自動化的工作負載（CI、正式環境服務），請由組織管理員建立服務帳戶，讓該工作負載擁有自己的身分。

工作區 API 金鑰仍可運作，但應視為舊版；建議優先使用以身分為基礎的金鑰或 Workload Identity Federation。若要遷移，請參閱取代工作區 API 金鑰。

建立並使用金鑰

• 建立金鑰： 前往 Claude Console 中的 Settings → API keys，然後點擊 Create key。為金鑰命名並選擇到期時間。若要建立個人金鑰，請將 Linked account 設為您自己；若要建立供多位使用者共用的金鑰，請設為某個服務帳戶。您也可以將金鑰的範圍限定於特定工作區，如此一來，日後的請求便可省略手動設定工作區 ID。
• 使用金鑰： 在直接的 HTTP 請求中設定 x-api-key 標頭，或設定 ANTHROPIC_API_KEY 環境變數，用戶端 SDK 會自動讀取它。

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

請將 API 金鑰儲存在密鑰管理工具中、定期輪替，並停用或刪除任何您懷疑已外洩的金鑰。在 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 的 Settings → Workspaces 中的 ID 欄位找到工作區的 ID，或呼叫 List Workspaces 端點取得。兩者皆不會列出 Default Workspace 的 ID：請從在該工作區執行的任何請求（例如使用來自 Default Workspace 的工作區金鑰所發出的請求）的 anthropic-workspace-id 回應標頭中讀取，或從 List API Keys 中此類金鑰的 scope.workspace_id 讀取。

client = Anthropic()  # reads ANTHROPIC_API_KEY

# 多工作區金鑰的每個請求皆為必填。
# 單一工作區金鑰請省略 extra_headers。
message = client.messages.create(
    model="claude-opus-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 keys 頁面建立 API 金鑰時，您需要選擇到期時間：預設選項（3 小時、1 天、7 天或 30 天）、自訂期間，或針對您儲存在密鑰管理工具中並自行輪替的金鑰選擇 Never。如果您的組織設有最長到期時間政策，Console 會將預設選項與自訂期間限制在政策上限內，且 Never 將無法使用。既有金鑰維持其目前的行為；到期時間於建立時設定，之後無法變更。當您在 Claude Console 中建立 Admin API 金鑰時，同樣適用此到期時間選項。

Anthropic 會在到期時間接近時寄送電子郵件給金鑰的建立者：對於建立時有效期至少 14 天的金鑰，於到期前 7 天通知；對於有效期至少 7 天的金鑰，於到期前 1 天通知。有效期更短的金鑰到期時不會寄送警告郵件。

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

Console 的 API keys 表格會顯示每把金鑰的到期時間，而 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 keys 頁面上刪除該工作區金鑰。

Workload Identity Federation

「Workload Identity Federation」（工作負載身分聯合），即 WIF，讓工作負載能夠使用由您已信任的「identity provider」（身分提供者），即 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 呼叫。

若要註冊您的應用程式並取得 client ID，請參閱適用於 iOS 與 macOS 應用程式的 App Attest。

後續步驟