用于终端客户归属的用户配置文件

"User profiles"（用户配置文件，简称"配置文件"）用于告诉 Anthropic 每个 API 请求是为您的哪个终端客户发出的。这样，"safety enforcement action"（安全执行措施），例如暂停（hold）或封禁（block），就可以仅作用于单个终端客户，而不是您的整个组织。在这种情况下，您的其余流量不受影响。

如果您运营平台或网关，或转售 API 访问权限，那么您为终端客户发送的请求都会归入您的组织。Anthropic 会对 API 流量运行自动化安全分类器。如果请求上没有配置文件，单个终端客户就可能触发作用于您整个组织的执行措施。

您只需使用 POST /v1/user_profiles 为每个终端客户注册一次，并存储返回的 uprof_ ID。然后，在您代表该终端客户发出的每个请求中，通过 anthropic-user-profile-id 标头发送该 ID。

配置文件不计费，也不影响定价。

确定为谁创建配置文件

配置文件代表什么取决于您销售 Claude 的方式：是使用您产品的个人，还是您向其转售 API 访问权限的公司。这两种情况涵盖了大多数平台。配置文件的 access_type 字段表明适用哪一种。

配置文件包含的内容以及 Anthropic 如何使用它

配置文件仅包含您发送的有关终端客户的信息，以及 Anthropic 设置的任何计划状态。它不包含对话内容。Anthropic 使用您发送的详细信息来归属请求、监控滥用行为、执行使用政策，以及支持申请和访问受信任访问计划。Anthropic 不会验证这些详细信息。

Anthropic 根据隐私政策处理配置文件。

开始之前

您可以在以下任一位置创建和管理配置文件：

• Claude API 上的组织。
• Claude Platform on AWS 上的组织。调用主体需要具有用户配置文件 IAM 操作权限。
• 托管在 Anthropic 上的 Microsoft Foundry 部署，而不是托管在 Azure 上的部署。您不需要 Claude API 或 Claude Platform on AWS 上的组织。请使用您的 Foundry 端点，以及与推理相同的基础 URL 和身份验证方式。

Amazon Bedrock 和 Google Cloud 没有 /v1/user_profiles 端点。如果您的推理在这些平台上运行，请在 Claude API 或 Claude Platform on AWS 上的组织中创建配置文件。在 Amazon Bedrock 上，配置文件仅适用于 Claude in Amazon Bedrock。请参阅在 Amazon Bedrock 和 Google Cloud 上归属请求。

请将您为终端客户发送的流量放在一个组织中，将您自己的内部使用放在另一个组织中。配置文件属于组织而不是工作区，因此在同一组织中使用不同的工作区是不够的。只有用于终端客户流量的组织需要用户配置文件。要在 Claude API 上创建另一个组织，请参阅 Claude 帮助中心中在 Claude Console 中创建和管理工作区一文的"How to create a new organization"（如何创建新组织）部分。

示例使用 API 密钥调用 Claude API。您不需要 Admin API 密钥。在 Claude Platform on AWS 上，请使用其基础 URL 和身份验证方式。

为每个终端客户创建配置文件

为您向 Claude 发送其流量的每个终端客户创建一个配置文件。请在您的客户入驻流程中创建一次。POST /v1/user_profiles 不是幂等的，因此每次调用都会创建一个新的配置文件，即使 reference_id 与现有配置文件相同也是如此。如果您已有尚未创建配置文件的终端客户，请参阅本节后面关于注册现有客户群的指导。

以下示例注册了一家通过网关购买 API 访问权限的公司，因此将 access_type 设置为 passthrough。对于 application 配置文件，请省略 access_type，并在 name 和 external_user_details 中描述单个终端用户，而不是公司。确定为谁创建配置文件比较了这两种访问类型。

client = anthropic.Anthropic()

profile = client.user_profiles.create(
    name="Acme Analytics, Inc.",
    access_type="passthrough",
    external_user_details={"reference_id": "cust-8f2a1c", "country": "US"},
)

print(profile.id)

响应即为新的配置文件：

{
  "type": "user_profile",
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "name": "Acme Analytics, Inc.",
  "access_type": "passthrough",
  "external_user_details": {
    "reference_id": "cust-8f2a1c",
    "onboarded_at": null,
    "account_status": null,
    "entity_type": null,
    "country": "US",
    "name_hash": null,
    "email_hash": null
  },
  "metadata": {},
  "programs": {
    "cyber": null,
    "efs": null
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

请将 id 存储在您的客户记录中，并让您的服务实例从那里读取它，而不是各自创建配置文件。您可以通过该 id 检索、更新和删除配置文件。programs 字段是只读的，归属不会使用它。它保存终端客户在 Anthropic 运行的每个计划中的状态。有关其取值的含义，请参阅哪些计划适用于配置文件。

一个组织中的配置文件数量没有上限，但配置文件的创建受"rate limit"（速率限制）约束。在批量注册现有客户群之前，请联系您的 Anthropic 客户团队。

向 Anthropic 提供哪些终端客户信息

所有字段都是可选的。您可以发送 name、metadata，以及 external_user_details 中的以下字段：entity_type、country、reference_id、onboarded_at、account_status、name_hash 和 email_hash。创建配置文件参考文档描述了每个字段及其类型、格式和长度限制。

设置字段时请遵循以下规则：

• 未知值： 如果您不知道某个值，请省略它，而不是发送占位值。您之后可以替换 external_user_details 中的值，但无法清除它。
• 公司名称： 对于 passthrough 配置文件，如果您知道公司的法定名称，请在 name 中发送。
• 国家/地区： 在 country 中发送终端客户所在的国家/地区，而不是您所在的国家/地区。
• 您自己的 ID： 在 reference_id 中发送您为该终端客户使用的稳定标识符。它不必是唯一的。
• 无法共享的姓名和电子邮件地址： 省略 name，改为发送 external_user_details.name_hash。对于电子邮件地址，请发送 external_user_details.email_hash。配置文件没有用于存放地址本身的字段。
• 哈希值： 请使用您选择的函数自行计算哈希值。它们可以向 Anthropic 表明您的哪些配置文件共享同一姓名或电子邮件地址。请对每个配置文件使用相同的函数以及相同的大小写和空白规范化方式，因为只有以相同方式计算的值才能匹配。

归属每个请求

在您代表终端客户发出的每个请求中，通过 anthropic-user-profile-id 标头发送配置文件 ID。SDK 和 CLI 提供了一个参数，可以为您发送该标头：user_profile_id。

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    user_profile_id="uprof_011CZkZCu8hGbp5mYRQgUmz9",
)

print(message)

该标头在令牌计数、Message Batches 和 OpenAI SDK 兼容性请求中的工作方式相同。在批处理中，它适用于批处理中的每个请求。

Claude API、Claude Platform on AWS 以及托管在 Anthropic 上的 Microsoft Foundry 部署会在每个请求中检查该 ID。如果 ID 格式错误或不属于发送请求的组织，API 会返回 400 invalid_request_error。默认情况下，这些平台仅在来自创建该配置文件的组织的请求中接受配置文件 ID。这意味着，如果您在多个组织下发送流量，例如一个在 Claude API 上、一个在 Claude Platform on AWS 上，那么来自未创建该配置文件的组织的请求也会收到同样的 400。

Message Batches 是个例外：创建批处理时只检查 ID 的格式。如果格式正确的 ID 不属于发送批处理的组织，批处理仍会被创建，但其中的每个请求随后都会失败，返回包含相同 invalid_request_error 的 errored 结果。

在 Amazon Bedrock 和 Google Cloud 上归属请求

任一访问类型的配置文件 ID 也适用于 Claude in Amazon Bedrock 和 Google Cloud。它不适用于您通过 InvokeModel 或 Converse 调用的早期 Amazon Bedrock 集成。您仅使用 Anthropic 组织的凭据来创建和管理配置文件。推理仍使用您现有的 AWS 或 Google Cloud 凭据。

在 Claude in Amazon Bedrock 上，请将 ID 放在请求体的顶层：

{
  "model": "anthropic.claude-opus-5-5",
  "max_tokens": 1024,
  "user_profile_id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "messages": [{ "role": "user", "content": "Hello, Claude" }]
}

请将每个向 Claude in Amazon Bedrock 发送请求的 AWS 账户，以及每个在 Google Cloud 上发送请求的 Google Cloud 项目，关联到创建您配置文件的 Anthropic 组织：

1. 该组织的管理员或所有者在 portal.anthropic.com 的 Verification Portal 中的 Linked accounts 下发起关联。
2. 能够管理该 AWS 账户或 Google Cloud 项目中 IAM 的人员运行门户提供的命令。
3. 管理员或所有者在门户中完成验证。

只有在账户完成关联且门户将其显示为 Linked 之后，适用于配置文件的计划才会适用于该账户的请求。这些计划包括终端客户将配置文件关联到其组织后，该组织获批的计划。

Claude in Amazon Bedrock 和 Google Cloud 会检查 ID 的格式，但不会查找配置文件。它们会以 400 拒绝格式错误的 ID。它们接受任何格式正确的 ID，因此成功的响应并不能确认该 ID 与某个配置文件匹配。不带 ID 的请求会在未归属的情况下通过，如果它触发了执行措施，该措施将作用于您的整个组织。

识别公司内的个人用户

passthrough 配置文件标识的是公司，而不是发出请求的个人。如果请求来自一个可识别的个人，请同时在 Messages 请求的 metadata.user_id 字段中发送该个人的标识符。这是请求自身的 metadata 对象，而不是配置文件的 metadata 字段。该标识符是可选的，它有助于 Anthropic 检测个人的滥用行为。

保持配置文件最新

当终端客户的详细信息或账户状态发生变化时，请更新配置文件；当他们关闭账户或要求您删除其数据时，请删除配置文件。

更新配置文件

POST /v1/user_profiles/{id} 仅更改您发送的字段。例如，当公司更名或您暂停某个账户时，可以使用它。

• name 和 access_type 会替换存储的值。
• 您在 external_user_details 中发送的每个字段都会替换存储的值。您无法清除值。API 会以 400 拒绝 null。
• metadata 按键合并。您发送的键会覆盖存储的值，空字符串会删除该键，您未发送的键保持不变。

以下示例将账户标记为已暂停，并删除 trial_cohort 元数据键。

client = anthropic.Anthropic()

profile = client.user_profiles.update(
    "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    external_user_details={"account_status": "suspended"},
    metadata={"trial_cohort": ""},
)

print(profile)

删除配置文件

DELETE /v1/user_profiles/{id} 会永久删除配置文件以及您为其提供的所有内容，包括 name、external_user_details 和 metadata。它不会删除 Anthropic 针对该配置文件 ID 保留的信任与安全记录。

当终端客户关闭账户或要求您删除其数据时，请删除配置文件。在删除配置文件之前，请停止在该终端客户的请求中发送其 ID。如果终端客户在提出删除请求后仍继续使用您的服务，请创建一个新的配置文件并切换到其 ID，然后删除旧的配置文件。

client = anthropic.Anthropic()

deleted = client.user_profiles.delete("uprof_011CZkZCu8hGbp5mYRQgUmz9")

print(deleted.id)

响应会重复该 ID，并带有 "type": "user_profile_deleted"。如果删除操作返回服务器错误，请重试。重试时返回 404 表示第一次删除已成功。

删除后，配置文件端点会对该 ID 返回 404。在最多约 10 分钟内，携带已删除 ID 的推理请求仍可能成功。此后，在每个请求中检查 ID 的平台会以 400 拒绝该请求。Claude in Amazon Bedrock 和 Google Cloud 不会查找配置文件，因此它们仍会接受该请求。

后续步骤

API 参考文档列出了每个端点的字段、类型和限制：创建配置文件、检索配置文件、更新配置文件和列出配置文件。

如果终端客户通过您的平台使用 Claude 时应适用其计划审批，请参阅向终端客户发送 Verification Portal 链接。