Claude API 身份验证：密钥、Bedrock、Vertex、Foundry

Claude API 的 4 种身份验证方式

Claude API 身份验证归结为一个选择：客户端将哪种凭据放入网络请求中。共有 4 种方式，它们并不是同一机制的不同变体。直接调用 Anthropic API 时，会在 x-api-key 请求头中发送静态密钥。Amazon Bedrock 使用 AWS 凭据为每个请求签名，这种配置中任何位置都不存在 Anthropic 密钥。Google Cloud 发送短期有效的 Google 访问令牌。Microsoft Foundry 使用 Azure 签发的密钥或 Microsoft Entra 令牌。

本指南介绍如何将 SDK（软件开发工具包）接入运行在 Linux 服务器上的服务。如果您配置的是 Claude Code 命令行工具，变量和流程会有所不同，请参阅 将 Claude Code 指向 Bedrock 或 Vertex。如果服务尚未创建，请先按照 在 VPS 上构建第一个 Claude API 应用 完成创建，然后返回此处配置凭据。

以下内容均已根据 Anthropic 在 August 2026 发布的平台文档进行核对。模型标识符、价格、SDK 版本和端点格式都会变化，因此本指南链接到各提供商的页面，而不是直接写入容易过时的值。

路径 1：Anthropic API 密钥

这是直接路径，也是唯一由 Anthropic 签发密钥的路径。请求发送到 Anthropic API 主机上的 Messages 端点，并且每个请求都携带 3 个请求头。

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": "MODEL_ID", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

将 MODEL_ID 替换为 Anthropic 模型概览中的当前标识符。成功响应是 JSON，其中包含 content 数组和 usage 对象。密钥错误或已过期时，服务器返回 HTTP 401 和 authentication_error。缺少 anthropic-version 请求头是另一种错误，因为每个请求都必须包含该请求头；SDK 会自动为您设置。

四种方式中，这种方式的客户端构造最简单，因为无需构造任何内容。所有官方 SDK 都会自行从环境中读取 ANTHROPIC_API_KEY。

import os
from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

message = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=64,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.usage)

将模型标识符与密钥一起放在环境变量中是值得的。模型名称会按您无法控制的计划发生变化，而为了修改一个字符串重新部署代码是可以避免的工作。

您可以在 Console 中创建密钥，并在创建时选择过期时间：3 hours、1 day、7 days 或 30 days 预设时长、自定义时长，或 Never。过期时间在创建时固定，之后无法更改。 Anthropic 会在长期密钥过期前向创建者发送邮件，但短期密钥过期时完全不会收到预警邮件。过期密钥会返回 401，且无法重新激活，因此解决方法始终是创建新密钥。

直接 API 无需选择区域，费用也会直接计入您的 Anthropic 组织。Workspace 可将密钥限定到一个项目，这是查看单个服务支出的最清晰方式。有关该账单的计算方式，请参阅按令牌计费的 API 定价与订阅价格的比较。

这里还应介绍另一种选项，因为它可以完全移除静态密钥。Workload Identity Federation 允许工作负载将在您已信任的身份提供商处获取的 OpenID Connect (OIDC) 令牌，交换为 POST /v1/oauth/token 处的短期 Anthropic 令牌；SDK 会在令牌过期前刷新它。系统不会生成或复制任何 sk-ant-api... 字符串。此方式适用于 Kubernetes、GitHub Actions 和云 VM，因为这些平台已经提供平台身份。普通 VPS 通常没有此类签发方，因此在这类主机上，将 API 密钥保存到文件中是实际可行的方案，本指南其余部分也按此方式处理。

Route 2：在 Amazon Bedrock 上使用 AWS 凭证

在 Bedrock 上，您完全不需要 Anthropic 密钥。SDK 使用常规 AWS 凭证，通过 AWS Signature Version 4（SigV4）为每个 HTTP 请求签名，然后由 AWS 判断该调用方是否可以调用模型。

pip install -U "anthropic[bedrock]"
aws sts get-caller-identity

aws sts get-caller-identity 会输出您的凭证解析到的身份对应的账户编号和 ARN（Amazon Resource Name，Amazon 资源名称）。在执行其他操作前先运行它。如果该命令失败，Claude 调用也会失败，因为 SDK 使用相同的凭证链：先读取构造函数参数，然后读取 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN 和 AWS_REGION 环境变量，接着读取 AWS 配置文件以及标准凭证链中的其他来源（SSO、assumed roles、ECS 任务角色和实例元数据服务）。

客户端构造方式只需修改类和一个参数。

from anthropic import AnthropicBedrock

client = AnthropicBedrock(aws_region="us-east-1")

在这里，区域不是可有可无的配置。Bedrock 端点按区域划分，模型访问权限需要在 AWS 控制台中按区域授予，而且区域属于 SigV4 签名的一部分。因此，为一个区域计算的签名会被另一个区域拒绝。在服务环境中明确设置 AWS_REGION。Anthropic 的文档说明，AnthropicBedrock 客户端会读取 AWS_REGION；如果该变量未设置，则回退到 us-east-1，并且不会使用 ~/.aws/config 读取区域。这就是为什么 AWS CLI 能在同一台主机上成功列出 Claude 模型，而您的 Python 进程却失败：CLI 读取了配置文件，但客户端没有读取。

在 EC2 实例上，您可以附加 IAM（identity and access management，身份和访问管理）角色。实例元数据服务会向 SDK 提供临时凭证，因此不会有密钥写入磁盘。AWS 外部的 VPS 既没有实例角色，也没有实例元数据服务。此时，您需要在以下方案中做出选择：将 IAM 用户的长期访问密钥对保存在主机上，这类机密与 Anthropic 密钥相同；或者使用联合身份验证：向身份提供商进行身份验证，调用 AWS STS（security token service，安全令牌服务），然后使用它返回的临时凭证。Bedrock 还支持通过 AWS_BEARER_TOKEN_BEDROCK 传递 bearer token。相关文档规定其最长有效期为 12 小时，AWS 将其描述为优先级最低的方案。

费用会计入您的 AWS 账户，而不是由 Anthropic 收取；这通常正是使用 Bedrock 的主要原因。根据 August 2026 的文档，区域端点的费用比全局端点高 10%。有一个 Bedrock 错误值得识别，因为它看起来像权限问题，但实际并非如此：Invocation of model ID ... with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model. 这是模型路由问题，修改凭证无法解决。

Vertex AI 上的 Google 凭据

Google Cloud 使用 Application Default Credentials（ADC）。这是 Google 身份验证库用于查找凭据的固定搜索顺序，无需您指定凭据。ADC 会先检查 GOOGLE_APPLICATION_CREDENTIALS，然后检查由 gcloud auth application-default login 写入的文件，最后检查通过元数据服务器关联的服务账号。

pip install -U "anthropic[vertex]"
gcloud auth application-default login

在工作站上，执行登录后会写入 $HOME/.config/gcloud/application_default_credentials.json，即可完成配置。在服务器上不应使用此工具，因为它保存的凭据属于某个用户，并会随该用户账号失效。在 Google Cloud 外部也没有元数据服务器，因此 ADC 最终会使用指向服务账号密钥文件的 GOOGLE_APPLICATION_CREDENTIALS。该 JSON 文件是长期有效的机密，必须按照本指南后文所述的方式严格管理。在 Google Cloud 内部，将服务账号关联到 VM，即可避免保护凭据文件。

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="my-project", region="global")

如果绕过 SDK 直接使用原始 HTTP，会有两点变化。模型标识符会从请求正文移到 URL 路径中，anthropic_version 会从标头移到正文中，并且必须写成 vertex-2023-10-16。该凭据就是普通的 Google 访问令牌。

curl https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/anthropic/models/${MODEL_ID}:rawPredict \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

区域是一个独立参数。global 会根据可用性动态路由，us 和 eu 是多区域标识符，而 us-east5 这样的名称会固定使用单个区域。根据 2026 年 8 月的文档，多区域端点和区域端点的费用比全球端点高 10%。计费通过 Google Cloud 项目执行，因此配额和账单由 Google 负责。

路线 4：Microsoft Foundry 是 Azure 路线

如果您是在 Azure 中搜索 Claude，那么需要查看的就是本节，并且确实存在受支持的路线。Claude 运行在 Microsoft Foundry（原 Azure AI Foundry）中，通过 Azure Marketplace 按 Claude Consumption Units 计费。您需要创建一个 Foundry 资源，在其中部署 Claude 模型，然后调用 Azure 托管的端点 https://{resource}.services.ai.azure.com/anthropic/v1/*。

有两种凭据可用。第一种是 Azure 颁发的密钥，可在 Foundry 门户中部署的 Details 选项卡中获取，并通过 api-key 或 x-api-key 标头发送。第二种是 Microsoft Entra 令牌。在服务器上，推荐使用这种方式，因为 Azure 基于角色的访问控制可以据此管理允许调用该端点的用户。

ACCESS_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl https://${RESOURCE}.services.ai.azure.com/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "DEPLOYMENT_NAME", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

model 字段携带的是部署名称，而不是模型标识符。默认情况下，两者名称相同；但只要您自行命名部署，它们就会立即不同。这通常是其他请求内容都正确但仍出现 Deployment not found 错误的原因。Python 和 TypeScript SDK 会从环境中读取 ANTHROPIC_FOUNDRY_API_KEY 和 ANTHROPIC_FOUNDRY_RESOURCE。并非所有 SDK 都支持 Foundry：根据 2026 年 8 月的文档，支持 C#、Java、PHP、Python 和 TypeScript；Go 和 Ruby SDK 则需要使用通用客户端，并将其指向 Foundry 基础 URL。

这种变通方案存在一个明显风险。如果环境中仍设置了 ANTHROPIC_API_KEY，通用客户端会读取该变量，并将您的 Anthropic 密钥发送到 Microsoft 端点。请取消设置该变量，或在客户端上禁用环境默认值。Entra 令牌大约 1 小时后过期，因此长时间运行的进程必须刷新令牌，不能在启动时只获取一次。

服务器上的凭据可以使用多长时间？

[
  {
    "label": "Anthropic key, 30-day preset",
    "max_lifetime_hours": 720
  },
  {
    "label": "Anthropic key, 7-day preset",
    "max_lifetime_hours": 168
  },
  {
    "label": "AWS STS assumed role",
    "max_lifetime_hours": 12
  },
  {
    "label": "Bedrock bearer token",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token",
    "max_lifetime_hours": 1
  },
  {
    "label": "Federated Anthropic token",
    "max_lifetime_hours": 1
  }
]

这些上限和默认值由各提供商发布，数据读取于 August 2026，并非实测值。它们的重要性在于：当您还在确认凭据已经泄露时，这些数据可以告诉您泄露的凭据还能继续工作多长时间。图表底部的短期令牌每个可持续 1 小时，SDK 会自动刷新，因此较短的有效期不会增加运维成本。通过 AssumeRole 获取的角色凭据有效期为 12 小时。使用 30-day 预设创建的密钥有效 720 小时；该凭据会在服务器上的文件中保存一个月。

VPS 上凭据的存放位置

将密钥放入只有 root 可读取的文件中，再让 systemd 将其传递给进程。这种做法不受 SDK 版本影响，因此值得一次正确配置，长期使用。

sudo useradd --system --home /opt/claude-app --shell /usr/sbin/nologin claudeapp
sudo install -d -m 700 -o root -g root /etc/claude-app
sudo install -m 600 -o root -g root /dev/null /etc/claude-app/env
sudoedit /etc/claude-app/env

该文件包含纯 KEY=value 行。不需要 export、引号或 shell 语法，因为 systemd 会自行解析它，而不是通过 shell 执行。

ANTHROPIC_API_KEY=sk-ant-api03-REPLACE-ME
CLAUDE_MODEL=REPLACE-ME

[Unit]
Description=Claude API service
After=network-online.target

[Service]
User=claudeapp
EnvironmentFile=/etc/claude-app/env
ExecStart=/opt/claude-app/venv/bin/python -m claude_app
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemd 以 root 身份读取 EnvironmentFile=，然后才降权为 User=claudeapp，因此服务账户不需要获得该文件的读取权限。将文件所有者设为 root、权限设为 600 即可，这也是上面的 install 命令这样设置的原因。使用 sudo systemctl enable --now claude-app 启动服务，然后通过 systemctl status claude-app 确认单元已进入 active (running)，而不是陷入循环重启。

以下 4 件事不要做。每一项都有明确原因，你可以自行验证：

• 不要在单元文件中使用 Environment= 写入密钥。/etc/systemd/system 下的单元文件对所有用户可读，因此 systemctl cat claude-app 会将密钥打印给任何本地用户。
• 不要提交该文件。.gitignore 只能阻止新文件进入提交，无法处理已经提交的文件，因为 git 历史会保留此前提交的内容。
• 不要将密钥写入容器镜像。ENV 行和 --build-arg 值会记录在镜像层中，docker history --no-trunc 会将其打印出来。在后续镜像层中删除文件，并不会从之前的层中删除它。应改用 --env-file 在运行时传递密钥，或挂载包含密钥的文件。
• 不要认为 root 无法读取进程环境。sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ 会将密钥打印出来。目标是让主机上的其他账户无法获取密钥，而不是阻止 root 获取，因为无论采用何种方式，root 都能读取它。

最后一点说明了这种设计的适用边界。当只有服务和 root 能读取环境变量时，使用环境变量保存密钥是可行的。如果进程会运行你未编写的代码，环境变量就不是合适的容器，因为进程能够执行的任何代码都可以读取自身的环境。避免让 AI 代理接触密钥介绍了这种情况。这是另一个问题，需要采用不同的解决方案。

如何在不中断服务的情况下轮换密钥？

先轮换，再撤销旧密钥。

1. 在 Console 中创建新密钥，使用与旧密钥相同的工作区。
2. 使用 sudoedit 将新密钥写入 /etc/claude-app/env。
3. 运行 sudo systemctl restart claude-app。
4. 确认服务能够响应请求后，再在 Console 中撤销旧密钥。

单元启动时会读取 EnvironmentFile，因此运行中的进程会继续使用启动时获得的值。systemctl daemon-reload 会重新读取单元文件，但不会修改运行中进程的环境变量，因此只有重启后才会使用新密钥。如果在第 1 步而不是第 4 步撤销旧密钥，服务会一直中断到第 3 步完成。

其他 3 种方式都在提供商侧轮换。IAM 用户可以同时拥有 2 个处于活动状态的访问密钥，因此先创建第二个密钥并部署，然后删除第一个密钥。Google 服务账号密钥的轮换方式相同。Foundry 密钥在门户中重新生成，旧密钥会立即失效，因此请先写入新值，再点击确认。Entra 令牌和联合 Anthropic 令牌完全不需要轮换；只要条件允许，这也是优先使用它们的最有力理由。

在 Console 中设置工作区的支出上限。密钥泄露首先会带来高额费用，其他后果反而在其之后；限制 VPS 上的代理可支出金额介绍了相关控制项。

为什么客户端返回 401 或 403？

直接 API 使用 authentication_error 时返回 401。 密钥错误、已撤销或已过期。用户最容易忽略过期问题，因为代码没有变化，而请求昨天还可以正常工作。在 Console 中检查密钥的过期时间列，或通过 Admin API 读取 expires_at。对于未设置过期时间的密钥，该值为 null。

SDK 忽略联合身份验证配置，改为使用密钥。 在凭据优先级中，ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 的优先级高于联合身份验证，因此任一配置都会覆盖联合身份验证。尤其要注意：导出为空字符串的变量仍会占用对应位置。因此，ANTHROPIC_API_KEY="" 会使 SDK 使用空密钥进行身份验证，而不会继续尝试后续配置。请使用 unset ANTHROPIC_API_KEY。

联合身份验证返回不带其他内容的 Authentication failed，状态码为 401。 对所有可能原因，系统都会有意返回相同的消息。这样，调用方无法通过读取错误文本来探测规则配置。实际原因会记录在 Console 的身份验证历史页面中。请先查看该页面，不要直接猜测 JWT 的问题。

Foundry 返回 403。 令牌已通过身份验证，但您的 Azure 账户缺少允许执行该调用的角色。请为发起请求的身份分配 Azure RBAC 角色，例如 Foundry User（原 Azure AI User）或 Cognitive Services User。

Bedrock 出现任何错误。 首先以服务用户身份运行 aws sts get-caller-identity。该命令可以确认主机是否拥有可用的 AWS 凭据，从而区分凭据问题、模型访问问题和区域不匹配问题。模型访问权限按区域在 AWS 控制台中授予。您可能在一个区域启用了权限，却调用了另一个区域。

FAQ

我需要 Anthropic API 密钥才能在 Bedrock 或 Vertex 上使用 Claude 吗？

不需要。在 Amazon Bedrock 上，SDK 使用 SigV4 通过 AWS 凭据为每个请求签名；在 Google Cloud 上，SDK 通过 Application Default Credentials 获取 Google 访问令牌并发送请求。这两种配置都不使用 Anthropic 签发的密钥，费用也计入云账户，而不是 Anthropic。这也是为什么在这些主机的 ANTHROPIC_API_KEY 中遗留 Anthropic 密钥会带来风险：指向云端点的通用客户端会直接将该密钥发送到那里。

Azure 提供 Claude 吗？

提供，可通过 Microsoft Foundry 使用。Microsoft Foundry 的旧名称是 Azure AI Foundry。您需要创建 Foundry 资源，在其中部署 Claude 模型，然后调用 https://{resource}.services.ai.azure.com/anthropic/v1/messages。请求可通过 api-key 头中的 Azure 签发密钥，或通过 Microsoft Entra bearer token 进行身份验证。费用通过 Azure Marketplace 按 Claude Consumption Units 计费。请求正文中的 model 字段必须填写您的部署名称。在您重命名部署之前，该名称才会与模型标识符相同。

应将 Claude API 密钥存储在 Linux 服务器的什么位置？

将其存储在 root 所有、权限为 600 的文件中，并通过 systemd 单元中的 EnvironmentFile= 加载。systemd 会在切换到单元的 User= 之前以 root 身份读取该文件，因此服务账户无需访问该文件。不要将密钥放入代码仓库、单元文件本身或容器镜像层中。单元文件可被所有用户读取，并会由 systemctl cat 打印；容器镜像中，docker history --no-trunc 会打印通过 ENV 或 --build-arg 设置的全部内容。

我的 Claude API 请求在没有任何改动的情况下开始返回 401，为什么？

最常见的原因是密钥已达到创建时设定的过期时间。过期时间在创建时设置，之后无法修改；短期密钥过期时不会发送警告邮件。过期密钥无法重新激活，因此请创建替代密钥，将其写入环境文件，重启服务，然后撤销旧密钥。如果确定密钥仍然有效，请检查是否有旧凭据覆盖了它：设置为空字符串的 ANTHROPIC_API_KEY 仍会优先于其他所有凭据来源。