身份验证

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 密钥页面（platform.claude.com/settings/keys）并点击创建密钥。为密钥命名并选择过期时间。对于个人密钥，将关联账户设置为您自己；对于在多个用户之间共享的密钥，将其设置为某个服务账户。您还可以将密钥限定到特定工作区，这样在以后的请求中就无需手动设置工作区 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 密钥页面上，禁用是可逆的（Admin API 会将密钥的 status 报告为 "inactive"，而重新启用会将其恢复为 "active"），而删除是永久性的：密钥会被归档，并仍以 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 的工作区页面（platform.claude.com/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 天）、自定义时长，或者对于您存储在密钥管理器中并自行轮换的密钥选择永不。如果您的组织有最大过期策略，Console 会将预设值和自定义时长限制为策略最大值，并且永不选项不可用。现有密钥保持其当前行为；过期时间在创建时设置，之后无法更改。当您在 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. 创建服务账户（如有必要）。您可能需要请组织管理员在 Claude Console 的服务账户页面（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) 允许工作负载使用由您已经信任的身份提供商 (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。

后续步骤