--- title: 身份驗證 url: https://platform.claude.com/docs/zh-TW/manage-claude/authentication description: 使用 API 金鑰、Workload Identity Federation 或 App Attest 向 Claude API 進行身份驗證。 --- Claude API 支援三種驗證請求的方式： | 方法 | 憑證 | 最適合 | | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- | | [API 金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#api-keys) | 作為 bearer token 在 `Authorization` 標頭中發送的靜態 `sk-ant-api...` 密鑰 | 本地開發、原型設計、腳本，以及您控制密鑰儲存的伺服器 | | [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#workload-identity-federation) | 從您的身份提供者的身份令牌交換而來的短期 bearer token | 雲端平台（AWS、Google Cloud、Azure）上的生產工作負載、CI/CD 管線和 Kubernetes，您希望消除靜態密鑰的場景 | | [App Attest](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#app-attest) | 發給您已註冊的 iOS 或 macOS 應用程式的真實、經過驗證的安裝的短期存取令牌 | 分發給終端使用者的 iOS 和 macOS 應用程式，應用程式直接呼叫 Claude API 而無需後端或代理 | API 金鑰和 Workload Identity Federation 授予對 Claude API 端點的相同存取權限。選擇 API 金鑰可快速上手：用於您自己開發的個人金鑰，或用於任何共享用途的服務帳戶金鑰。當您的工作負載已經擁有可以聯合的平台發行身份時，請改用 Workload Identity Federation。對於您分發給終端使用者的 iOS 和 macOS 應用程式，請使用 App Attest。 ## API 金鑰 API 金鑰是您在 Claude Console 中生成的靜態密鑰，並在每個請求中作為 bearer token 在 `Authorization` 標頭中發送。 ### 金鑰類型 當您建立金鑰時，您會選擇其類型，這決定了金鑰可以做什麼、在哪裡運作，以及何時停止運作： | 金鑰類型 | 作為 | 運作於 | 停止運作的時機 | | ------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------- | | **個人金鑰** | 您，即使用者，具有您的角色和權限 | 單一工作區，或您的角色允許使用 API 的工作區，在建立金鑰時選擇 | 您失去對組織的存取權，或對於單一工作區金鑰，失去對該工作區的存取權。當您從組織中被移除時，個人金鑰會被封存。如果您被重新邀請，請建立新金鑰；已封存的金鑰不會被還原 | | **服務帳戶金鑰** | 一個[服務帳戶](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation#service-accounts) | 單一工作區，或服務帳戶有權存取的任何內容，在建立金鑰時選擇。服務帳戶可存取預設工作區以及已被加入的工作區 | 服務帳戶被封存，或對於單一工作區金鑰，從該工作區被移除 | | **工作區金鑰**（舊版） | 無人：它屬於建立它的工作區 | 該工作區 | 它過期、被停用或刪除，或其工作區被封存，無論其建立者是否離開組織 | 個人金鑰和服務帳戶金鑰是身份支援的：每個金鑰都屬於您的組織已經管理的使用者或服務帳戶，且每個請求都以該身份行事。當該身份從組織中被移除時，金鑰就會停止運作。這意味著金鑰不會意外地比擁有它們的人員或工作負載存活更久。對於新的整合，請優先使用它們而非工作區金鑰。 使用個人金鑰進行您自己的開發和腳本。共享的個人金鑰作為一個人行事，並在該人離開時失效。對於共享或自動化的工作負載（CI、生產服務），請讓組織管理員建立服務帳戶，以便工作負載擁有自己的身份。 工作區 API 金鑰仍然可以運作，但應被視為舊版；身份支援的金鑰或 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation) 是首選。要遷移，請參閱[替換工作區 API 金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#replacing-workspace-api-keys)。 ### 建立和使用金鑰 * **建立金鑰：** 在 Claude Console 中，前往 [API 金鑰](https://platform.claude.com/settings/keys)頁面（`platform.claude.com/settings/keys`）並點擊 **Create key**。為金鑰命名並選擇[過期時間](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-expiration)。若要建立個人金鑰，請將 **Linked account** 設為您自己；若要建立供多位使用者共享的金鑰，請設為服務帳戶。您也可以將金鑰限定於特定工作區，如此在之後的請求中就不必手動設定工作區 ID。 * **使用金鑰：** 在直接 HTTP 請求中將其作為 `Authorization: Bearer ` 發送，或設定 `ANTHROPIC_API_KEY` 環境變數，[用戶端 SDK](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/overview) 會自動取用它。 ```http 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 金鑰頁面](https://platform.claude.com/settings/keys)上，**Disable** 是可逆的（Admin API 會將金鑰的 `status` 回報為 `"inactive"`，而 **Re-enable** 會將其恢復為 `"active"`），而 **Delete** 則是永久性的：金鑰會被封存，並仍以 `status: "archived"` 出現在 [List API Keys](https://platform.claude.com/docs/zh-TW/api/organization/api_keys/list) 中。已過期的金鑰只能被刪除。您也可以在建立金鑰時設定[過期時間](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-expiration)，以限制洩漏憑證可被使用的時間長度。 ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```python Python client = Anthropic(api_key="my-anthropic-api-key") # 或者，在環境中設定 ANTHROPIC_API_KEY 後： client = Anthropic() ``` ```typescript TypeScript const client = new Anthropic({ apiKey: "my-anthropic-api-key" }); // 或者，在環境中設定 ANTHROPIC_API_KEY 後： // const client = new Anthropic(); ``` ```go Go client := anthropic.NewClient( option.WithAPIKey("sk-ant-api03-..."), // defaults to os.LookupEnv("ANTHROPIC_API_KEY") ) ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; // 明確指定 AnthropicClient client = AnthropicOkHttpClient.builder() .apiKey("my-anthropic-api-key") .build(); // 來自 ANTHROPIC_API_KEY（或 anthropic.apiKey 系統屬性） AnthropicClient clientFromEnv = AnthropicOkHttpClient.fromEnv(); ``` ```csharp C# using Anthropic; AnthropicClient client = new() { ApiKey = "my-anthropic-api-key" }; // 或者，在環境中設定 ANTHROPIC_API_KEY 後： // AnthropicClient client = new(); ``` ```php PHP // 從環境變數讀取 ANTHROPIC_API_KEY $client = new Client(); // 或明確傳入金鑰： $client = new Client(apiKey: 'my-anthropic-api-key'); ``` ```ruby Ruby anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key") # 或者，在環境中設定 ANTHROPIC_API_KEY 後： anthropic = Anthropic::Client.new ``` ```bash CLI # 請參閱 /docs/en/cli-sdks-libraries/cli/authentication#api-key 以取得 zsh、bash 與 Windows 的變體 export ANTHROPIC_API_KEY=sk-ant-api03-... ``` ### 選擇工作區 為特定工作區建立的 API 金鑰僅在該工作區中運作，使用這些金鑰的 API 請求可以省略工作區 ID。 如果您的 API 金鑰未限定於某個工作區，您必須在每個請求的 `anthropic-workspace-id` 標頭中指定工作區 ID。請參閱以下範例，了解如何在請求或 SDK 中設定此標頭。 [Admin API](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api) 僅在金鑰未限定於特定工作區時才接受個人金鑰或服務帳戶金鑰。 您可以在 Claude Console 的 [Workspaces](https://platform.claude.com/settings/workspaces) 頁面（`platform.claude.com/settings/workspaces`）的 **ID** 欄位中找到工作區的 ID，或呼叫 [List Workspaces](https://platform.claude.com/docs/zh-TW/api/organization/workspaces/list) 端點取得。List Workspaces 僅在您傳入 `include_default=true` 時才會包含預設工作區；其 ID 也會出現在任何於該工作區執行之請求的 `anthropic-workspace-id` [回應標頭](https://platform.claude.com/docs/zh-TW/manage-claude/workspaces#identify-the-workspace-behind-an-api-response)中。 ```bash cURL # 多工作區金鑰的每個請求都必須提供。 # 單一工作區金鑰請省略 anthropic-workspace-id 標頭。 curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```bash CLI # 使用多工作區金鑰時，每個指令都必須提供。 # 使用單一工作區金鑰時，請省略 --workspace-id。 ant messages create \ --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \ --model claude-opus-5-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` ```python Python 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"}, ) ``` ```typescript TypeScript const client = new Anthropic(); // reads ANTHROPIC_API_KEY // 多工作區金鑰的每個請求都必須提供。 // 單一工作區金鑰請省略第二個引數。 const message = await client.messages.create( { model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }, { headers: { "anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } } ); console.log(message.content); // 或為此用戶端的每個請求設定一次： const workspaceClient = new Anthropic({ defaultHeaders: { "anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } }); ``` ```csharp C# AnthropicClient client = new(); // reads ANTHROPIC_API_KEY MessageCreateParams parameters = new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }], }; // 對於多工作區金鑰，每個請求都必須提供。 // 對於單一工作區金鑰，請直接呼叫 client.Messages.Create(parameters)。 var message = await client .WithOptions(options => options with { ExtraHeaders = new Dictionary { ["anthropic-workspace-id"] = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", }, } ) .Messages.Create(parameters); Console.WriteLine(message); // 或者為此用戶端的每個請求設定一次： AnthropicClient workspaceClient = new(new ClientOptions { ExtraHeaders = new Dictionary { ["anthropic-workspace-id"] = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ", }, }); ``` ```go Go client := anthropic.NewClient() // reads ANTHROPIC_API_KEY // 對於多工作區金鑰，每個請求都必須提供。 // 對於單一工作區金鑰，請省略此選項。 message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }, option.WithHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")) if err != nil { log.Fatal(err) } fmt.Println(message.Content) // 或者為此用戶端的每個請求設定一次： workspaceClient := anthropic.NewClient( option.WithHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"), ) ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // reads ANTHROPIC_API_KEY // 多工作區金鑰的每個請求都必須提供。 // 單一工作區金鑰請省略 putAdditionalHeader。 Message message = client.messages().create(MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .putAdditionalHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ") .build()); IO.println(message.content()); // 或為此用戶端的每個請求設定一次： AnthropicClient workspaceClient = AnthropicOkHttpClient.builder() .fromEnv() .putHeader("anthropic-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ") .build(); ``` ```php PHP $client = new Client(); // reads ANTHROPIC_API_KEY // 多工作區金鑰的每個請求都必須提供。 // 單一工作區金鑰請省略 requestOptions。 $message = $client->messages->create( model: Model::CLAUDE_OPUS_5_5, maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello, Claude']], requestOptions: [ 'extraHeaders' => ['anthropic-workspace-id' => 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'], ], ); echo json_encode($message->content), PHP_EOL; ``` ```ruby Ruby client = Anthropic::Client.new # reads ANTHROPIC_API_KEY # 多工作區金鑰的每個請求都必須提供。 # 單一工作區金鑰請省略 request_options。 message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], request_options: {extra_headers: {"anthropic-workspace-id" => "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"}} ) puts message.content ``` 如果使用未限定於工作區的金鑰發出的請求省略了標頭，API 會回傳 400 `invalid_request_error`： ```json JSON { "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 `` not found.``，與任何未知工作區的回應相同。 Workload Identity Federation 改為在令牌交換時選擇工作區；詳情請參閱 [WIF 參考](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference)。 ### 金鑰過期 當您從 Claude Console 中的 [API 金鑰頁面](https://platform.claude.com/settings/keys)建立 API 金鑰時，您會選擇過期時間：預設值（3 小時、1 天、7 天或 30 天）、自訂持續時間，或對於您儲存在密鑰管理器中並自行輪換的金鑰選擇 **Never**。如果您的組織有最大過期政策，Console 會將預設值和自訂持續時間限制為政策最大值，且 **Never** 不可用。現有金鑰保持其當前行為；過期時間在建立時設定，之後無法更改。當您在 Claude Console 中[建立 Admin API 金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api-keys)時，適用相同的過期選擇。 Anthropic 會在過期臨近時向金鑰的建立者發送電子郵件：對於生命週期至少 14 天的金鑰，在過期前 7 天發送；對於生命週期至少 7 天的金鑰，在過期前 1 天發送。生命週期較短的金鑰會在沒有警告電子郵件的情況下過期。 金鑰過期後，使用它發出的請求會回傳 `401 authentication_error`。建立新金鑰以恢復存取；過期的金鑰無法重新啟用。 Console 的 API 金鑰表格會顯示每個金鑰的過期時間，而 Admin API 會在 [List API Keys](https://platform.claude.com/docs/zh-TW/api/organization/api_keys/list) 和 [Retrieve API Key](https://platform.claude.com/docs/zh-TW/api/organization/api_keys/retrieve) 端點上回報每個金鑰的 `expires_at` 時間戳記，讓您可以在金鑰過期前進行稽核和輪換。對於沒有過期時間的金鑰，此欄位為 `null`。 過期時間限制了洩漏憑證的生命週期，但它不能替代密鑰衛生。無論過期時間如何，都應將金鑰儲存在密鑰管理器中，並停用或刪除任何您懷疑已洩漏的金鑰。 ### 替換工作區 API 金鑰 如果您有工作區金鑰，您可能想用 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference) 或個人或服務帳戶金鑰來替換它。這提供了更好的安全性和可觀察性。 有關配置 Workload Identity Federation 的詳情，請參閱 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference)，它比長期金鑰更受青睞。 要用個人或服務帳戶金鑰替換工作區金鑰： 1. **決定金鑰類型。** 您自己的工具應使用個人金鑰。共享或無人值守的工作負載應使用服務帳戶金鑰。 2. **視需要建立服務帳戶。** 您可能需要請組織管理員在 Claude Console 的 [Service accounts](https://platform.claude.com/settings/service-accounts) 頁面（`platform.claude.com/settings/service-accounts`）上建立服務帳戶，並將其加入相關的工作區。 3. **建立新金鑰。** 除非需要多個工作區，否則專門為整合的工作區建立它。 4. **部署新金鑰。** 在整合讀取它的任何地方替換舊金鑰，通常是 `ANTHROPIC_API_KEY` 環境變數或密鑰管理器條目。對於多工作區金鑰，還需如[選擇工作區](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#select-a-workspace)所示發送 `anthropic-workspace-id` 標頭。 5. **刪除舊金鑰。** 確認請求成功後，在 Claude Console 的 [API 金鑰頁面](https://platform.claude.com/settings/keys)上刪除工作區金鑰。 ## 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](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation)。 ## App Attest App Attest 驗證直接從裝置呼叫 Claude API 的 iOS 和 macOS 應用程式。每個安裝都使用 Apple 的 App Attest 服務證明它是您在 Claude Console 中註冊的應用程式的真實、未修改的建置。然後 Anthropic 向裝置發行一個短期存取令牌，將使用量計費到您的工作區。令牌限定於您的工作區，一小時後過期，並僅授權 [Messages API](https://platform.claude.com/docs/zh-TW/api/messages/create) 呼叫。 要註冊您的應用程式並取得用戶端 ID，請參閱 [iOS 和 macOS 應用程式的 App Attest](https://platform.claude.com/docs/zh-TW/manage-claude/app-attest)。 ## 後續步驟 配置發行者、規則和服務帳戶，然後交換令牌 AWS、Google Cloud、Azure、GitHub Actions、Kubernetes、SPIFFE 和 Okta 的逐步指南 環境變數、驗證規則、設定檔配置和錯誤參考 讓您應用程式的真實安裝在不附帶 API 金鑰的情況下呼叫 Claude API Python、TypeScript、C#、Go、Java、PHP、Ruby 和 CLI