身份验证

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

API 密钥和 Workload Identity Federation 授予对 Claude API 端点的相同访问权限。选择 API 密钥可快速上手，当您的工作负载已经拥有可联合的平台颁发身份时，再迁移到 Workload Identity Federation。对于分发给最终用户的 iOS 和 macOS 应用，请使用 App Attest。



API 密钥

API 密钥是您在 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，允许工作负载使用由您已信任的身份提供商（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。



后续步骤