--- title: 身份验证 url: https://platform.claude.com/docs/zh-CN/manage-claude/authentication description: 使用 API 密钥、Workload Identity Federation 或 App Attest 向 Claude API 进行身份验证。 --- Claude API 支持三种对请求进行身份验证的方式： | 方法 | 凭据 | 最适合 | | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | | [API 密钥](https://platform.claude.com/docs/zh-CN/manage-claude/authentication#api-keys) | 作为 bearer token 在 `Authorization` 标头中发送的静态 `sk-ant-api...` 密钥 | 本地开发、原型设计、脚本以及您控制密钥存储的服务器 | | [Workload Identity Federation](https://platform.claude.com/docs/zh-CN/manage-claude/authentication#workload-identity-federation) | 从您的身份提供商的身份令牌交换而来的短期 bearer token | 云平台（AWS、Google Cloud、Azure）上的生产工作负载、CI/CD 流水线以及 Kubernetes，在这些场景中您希望消除静态密钥 | | [App Attest](https://platform.claude.com/docs/zh-CN/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-CN/manage-claude/workload-identity-federation#service-accounts) | 单个工作区，或服务账户有权访问的任何内容，在创建密钥时选择。服务账户可以访问默认工作区以及它被添加到的工作区 | 服务账户被归档，或者对于单工作区密钥，从该工作区中被移除 | | **工作区密钥**（旧版） | 无人：它属于创建它的工作区 | 该工作区 | 它过期、被禁用或删除，或其工作区被归档，无论其创建者是否离开组织 | 个人密钥和服务账户密钥是基于身份的：每个密钥都属于您的组织已经管理的用户或服务账户，并且每个请求都以该身份执行。当该身份从组织中被移除时，密钥就会停止工作。这意味着密钥不会意外地比拥有它们的人员或工作负载存活得更久。对于新集成，请优先使用它们而非工作区密钥。 将个人密钥用于您自己的开发和脚本。共享的个人密钥充当一个人，当该人离开时就会失效。对于共享或自动化的工作负载（CI、生产服务），请让组织管理员创建一个服务账户，以便工作负载拥有自己的身份。 工作区 API 密钥仍然有效，但应被视为旧版；基于身份的密钥或 [Workload Identity Federation](https://platform.claude.com/docs/zh-CN/manage-claude/workload-identity-federation) 是首选。要进行迁移，请参阅[替换工作区 API 密钥](https://platform.claude.com/docs/zh-CN/manage-claude/authentication#replacing-workspace-api-keys)。 ### 创建和使用密钥 * **创建密钥：** 在 Claude Console 中，前往 [API 密钥](https://platform.claude.com/settings/keys)页面（`platform.claude.com/settings/keys`）并点击**创建密钥**。为密钥命名并选择[过期时间](https://platform.claude.com/docs/zh-CN/manage-claude/authentication#key-expiration)。对于个人密钥，将**关联账户**设置为您自己；对于在多个用户之间共享的密钥，将其设置为某个服务账户。您还可以将密钥限定到特定工作区，这样在以后的请求中就无需手动设置工作区 ID。 * **使用密钥：** 在直接 HTTP 请求中将其作为 `Authorization: Bearer ` 发送，或设置 `ANTHROPIC_API_KEY` 环境变量，[客户端 SDK](https://platform.claude.com/docs/zh-CN/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)上，**禁用**是可逆的（Admin API 会将密钥的 `status` 报告为 `"inactive"`，而**重新启用**会将其恢复为 `"active"`），而**删除**是永久性的：密钥会被归档，并仍以 `status: "archived"` 出现在 [List API Keys](https://platform.claude.com/docs/zh-CN/api/organization/api_keys/list) 中。已过期的密钥只能被删除。您还可以在创建密钥时设置[过期时间](https://platform.claude.com/docs/zh-CN/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 # 有关 zsh、bash 和 Windows 的变体，请参阅 /docs/en/cli-sdks-libraries/cli/authentication#api-key export ANTHROPIC_API_KEY=sk-ant-api03-... ``` ### 选择工作区 为特定工作区创建的 API 密钥仅在该工作区中有效，使用这些密钥的 API 请求可以省略工作区 ID。 如果您的 API 密钥未限定到某个工作区，则必须在每个请求的 `anthropic-workspace-id` 标头中指定工作区 ID。请参阅以下示例，了解如何在请求或 SDK 中设置此标头。 [Admin API](https://platform.claude.com/docs/zh-CN/manage-claude/admin-api) 仅在密钥未限定到特定工作区时才接受个人密钥或服务账户密钥。 您可以在 Claude Console 的[工作区](https://platform.claude.com/settings/workspaces)页面（`platform.claude.com/settings/workspaces`）的 **ID** 列中找到工作区的 ID，也可以调用 [List Workspaces](https://platform.claude.com/docs/zh-CN/api/organization/workspaces/list) 端点获取。仅当您传入 `include_default=true` 时，List Workspaces 才会包含默认工作区；其 ID 也会出现在任何在该工作区中运行的请求的 `anthropic-workspace-id` [响应标头](https://platform.claude.com/docs/zh-CN/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-CN/manage-claude/wif-reference)。 ### 密钥过期 当您从 Claude Console 中的 [API 密钥页面](https://platform.claude.com/settings/keys)创建 API 密钥时，您需要选择过期时间：预设值（3 小时、1 天、7 天或 30 天）、自定义时长，或者对于您存储在密钥管理器中并自行轮换的密钥选择**永不**。如果您的组织有最大过期策略，Console 会将预设值和自定义时长限制为策略最大值，并且**永不**选项不可用。现有密钥保持其当前行为；过期时间在创建时设置，之后无法更改。当您在 Claude Console 中[创建 Admin API 密钥](https://platform.claude.com/docs/zh-CN/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-CN/api/organization/api_keys/list) 和 [Retrieve API Key](https://platform.claude.com/docs/zh-CN/api/organization/api_keys/retrieve) 端点上报告每个密钥的 `expires_at` 时间戳，以便您在密钥过期前进行审计和轮换。对于没有过期时间的密钥，该字段为 `null`。 过期时间限制了泄露凭据的生命周期，但它不能替代密钥卫生管理。无论是否过期，都应将密钥存储在密钥管理器中，并禁用或删除任何您怀疑已泄露的密钥。 ### 替换工作区 API 密钥 如果您有工作区密钥，您可能希望用 [Workload Identity Federation](https://platform.claude.com/docs/zh-CN/manage-claude/wif-reference) 或个人或服务账户密钥来替换它。这提供了更好的安全性和可观测性。 有关配置 Workload Identity Federation 的详细信息，请参阅 [Workload Identity Federation](https://platform.claude.com/docs/zh-CN/manage-claude/wif-reference)，它比长期密钥更受青睐。 要用个人或服务账户密钥替换工作区密钥： 1. **决定密钥类型。** 您自己的工具应使用个人密钥。共享或无人值守的工作负载应使用服务账户密钥。 2. **创建服务账户**（如有必要）。您可能需要请组织管理员在 Claude Console 的[服务账户](https://platform.claude.com/settings/service-accounts)页面（`platform.claude.com/settings/service-accounts`）上创建一个服务账户，并将其添加到相关工作区。 3. **创建新密钥。** 除非需要多个工作区，否则专门为集成的工作区创建它。 4. **部署新密钥。** 在集成读取密钥的任何位置替换旧密钥，通常是 `ANTHROPIC_API_KEY` 环境变量或密钥管理器条目。对于多工作区密钥，还需按照[选择工作区](https://platform.claude.com/docs/zh-CN/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-CN/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-CN/api/messages/create) 调用。 要注册您的应用并获取客户端 ID，请参阅 [适用于 iOS 和 macOS 应用的 App Attest](https://platform.claude.com/docs/zh-CN/manage-claude/app-attest)。 ## 后续步骤 配置颁发者、规则和服务账户，然后交换令牌 AWS、Google Cloud、Azure、GitHub Actions、Kubernetes、SPIFFE 和 Okta 的分步指南 环境变量、验证规则、配置文件配置和错误参考 让您应用的真实安装实例无需附带 API 密钥即可调用 Claude API Python、TypeScript、C#、Go、Java、PHP、Ruby 和 CLI