身份验证

Claude API 支持两种请求身份验证方式：

两种方法都授予对 Claude API 端点的相同访问权限。选择 API 密钥可以快速上手，当您的工作负载已经拥有可以联合的平台颁发的身份时，再迁移到 Workload Identity Federation。



API 密钥

API 密钥（API key）是您在 Claude Console 中生成并在每个请求中传递的静态密钥。

• 创建密钥： 前往 Claude Console 中的设置 → API 密钥。您在创建时选择过期时间。使用工作区按项目或环境对密钥进行范围划分。
• 发送密钥： 在直接 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 密钥存储在密钥管理器中，定期轮换，并撤销任何您怀疑已泄露的密钥。您还可以在创建密钥时设置过期时间，以限制泄露的凭证保持可用的时间。

client = Anthropic(api_key="my-anthropic-api-key")
# 或者，在环境中设置 ANTHROPIC_API_KEY 后：
client = Anthropic()



密钥过期

当您从 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 会在列出 API 密钥和检索 API 密钥端点上报告每个密钥的 expires_at 时间戳，因此您可以在密钥过期之前进行审计和轮换。对于没有过期时间的密钥，该字段为 null。

过期时间限制了泄露凭证的生命周期，但它不能替代密钥卫生管理。无论过期时间如何，都应将密钥存储在密钥管理器中，并撤销任何您怀疑已泄露的密钥。



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 了解完整的设置演练。



后续步骤