Профили пользователей для атрибуции конечных клиентов

Профили пользователей («user profiles», далее — «профили») сообщают Anthropic, для какого из ваших конечных клиентов предназначен каждый запрос API. Тогда мера воздействия по соображениям безопасности («enforcement action»), например приостановка или блокировка, может применяться к одному конечному клиенту, а не ко всей вашей организации. В этом случае остальной ваш трафик не затрагивается.

Если вы управляете платформой или шлюзом либо перепродаёте доступ к API, запросы, которые вы отправляете для своих конечных клиентов, поступают от имени вашей организации. Anthropic применяет к трафику API автоматические классификаторы безопасности. Если в запросе нет профиля, один конечный клиент может вызвать меру воздействия, которая применится ко всей вашей организации.

Вы регистрируете каждого конечного клиента один раз с помощью POST /v1/user_profiles и сохраняете возвращаемый идентификатор uprof_. Затем вы отправляете этот идентификатор в заголовке anthropic-user-profile-id в каждом запросе, который вы делаете от имени этого конечного клиента.

Профили не тарифицируются и не влияют на цены.

Кому нужен профиль

То, что представляет профиль, зависит от того, как вы продаёте Claude: это либо человек, который пользуется вашим продуктом, либо компания, которой вы перепродаёте доступ к API. Эти два случая охватывают большинство платформ. Поле access_type профиля указывает, какой из них применяется.

Что содержит профиль и как Anthropic его использует

Профиль содержит только то, что вы отправляете о конечном клиенте, а также любой статус программы, который устанавливает Anthropic. Он не содержит содержимое разговоров. Anthropic использует отправленные вами сведения для атрибуции запросов, мониторинга злоупотреблений, обеспечения соблюдения Политики использования, а также для обеспечения возможности подачи заявок на участие в программах доверенного доступа и доступа к ним. Anthropic не проверяет эти сведения.

Anthropic обрабатывает профили в соответствии с Политикой конфиденциальности.

Перед началом работы

Вы создаёте профили и управляете ими в одном из следующих мест:

• Организация в Claude API.
• Организация в Claude Platform on AWS. Вызывающему субъекту нужны действия IAM для профилей пользователей.
• Развёртывание Microsoft Foundry, размещённое в Anthropic, а не в 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, см. раздел «How to create a new organization» статьи Creating and managing Workspaces in the Claude Console в Справочном центре Claude.

В примерах Claude API вызывается с ключом 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 отправляйте страну конечного клиента, а не свою.
• Ваш собственный идентификатор: в reference_id отправляйте свой собственный стабильный идентификатор конечного клиента. Он не обязан быть уникальным.
• Имена и адреса электронной почты, которыми вы не можете поделиться: не указывайте name, а вместо этого отправьте external_user_details.name_hash. Для адреса электронной почты отправьте external_user_details.email_hash. В профиле нет поля для самого адреса.
• Хэши: вычисляйте хэши самостоятельно с помощью выбранной вами функции. Они показывают Anthropic, какие из ваших профилей имеют общее имя или адрес электронной почты. Используйте одну и ту же функцию и одинаковую нормализацию регистра и пробелов для всех профилей, потому что совпадают только значения, вычисленные одинаково.

Атрибуция каждого запроса

Отправляйте идентификатор профиля в заголовке anthropic-user-profile-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 и развёртывания Microsoft Foundry, размещённые в Anthropic, проверяют идентификатор в каждом запросе. Если идентификатор имеет неверный формат или не принадлежит организации, отправляющей запрос, API возвращает 400 invalid_request_error. По умолчанию эти платформы принимают идентификатор профиля только в запросах от организации, создавшей профиль. Это означает, что если вы отправляете трафик от имени нескольких организаций, например одной в Claude API и одной в Claude Platform on AWS, запрос от организации, которая не создавала профиль, получит тот же 400.

Исключение составляет Message Batches: при создании пакета проверяется только формат идентификатора. Если идентификатор правильного формата не принадлежит организации, отправляющей пакет, пакет всё равно создаётся, а затем каждый запрос в нём завершается результатом errored, содержащим тот же invalid_request_error.

Атрибуция запросов в Amazon Bedrock и Google Cloud

Идентификатор профиля любого типа доступа также работает в Claude in Amazon Bedrock и в Google Cloud. Он не работает с более ранней интеграцией Amazon Bedrock, которую вы вызываете с помощью InvokeModel или Converse. Учётные данные вашей организации Anthropic используются только для создания профилей и управления ими. Инференс по-прежнему выполняется с вашими существующими учётными данными AWS или Google Cloud.

В Claude in Amazon Bedrock поместите идентификатор на верхний уровень тела запроса:

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

Свяжите каждую учётную запись AWS, которая отправляет запросы в Claude in Amazon Bedrock, и каждый проект Google Cloud, который отправляет запросы в Google Cloud, с организацией Anthropic, создающей ваши профили:

1. Администратор или владелец этой организации начинает связывание в Verification Portal по адресу portal.anthropic.com в разделе Linked accounts.
2. Человек, который может управлять IAM в учётной записи AWS или проекте Google Cloud, выполняет команду, предоставленную порталом.
3. Администратор или владелец завершает проверку на портале.

Программы, применяемые к профилю, применяются к запросам учётной записи только после того, как учётная запись связана и портал показывает её как Linked. К таким программам относятся те, для которых одобрена организация конечного клиента после того, как конечный клиент свяжет профиль с этой организацией.

Claude in Amazon Bedrock и Google Cloud проверяют формат идентификатора, но не ищут профиль. Они отклоняют идентификатор неверного формата с кодом 400. Они принимают любой идентификатор правильного формата, поэтому успешный ответ не подтверждает, что идентификатор соответствует профилю. Запрос без идентификатора проходит без атрибуции, и если он вызовет меру воздействия, эта мера применится ко всей вашей организации.

Идентификация отдельных пользователей внутри компании

Профиль passthrough идентифицирует компанию, а не человека, делающего запрос. Если запрос исходит от одного идентифицируемого человека, также отправьте идентификатор этого человека в поле metadata.user_id запроса Messages. Это собственный объект metadata запроса, а не поле metadata профиля. Идентификатор необязателен, и он помогает Anthropic выявлять злоупотребления со стороны одного человека.

Поддержание профилей в актуальном состоянии

Обновляйте профиль, когда меняются сведения о конечном клиенте или статус его учётной записи, и удаляйте его, когда клиент закрывает учётную запись или просит вас удалить его данные.

Обновление профиля

POST /v1/user_profiles/{id} изменяет только отправленные вами поля. Например, используйте его, когда компания проводит ребрендинг или вы приостанавливаете учётную запись.

• name и access_type заменяют сохранённое значение.
• Каждое поле, которое вы отправляете в external_user_details, заменяет сохранённое значение. Очистить значение нельзя. API отклоняет null с кодом 400.
• 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 хранит об этом идентификаторе профиля.

Удаляйте профиль, когда конечный клиент закрывает учётную запись или просит вас удалить его данные. Прежде чем удалить профиль, перестаньте отправлять его идентификатор в запросах этого конечного клиента. Если после запроса на удаление данных конечный клиент остаётся с вами, создайте новый профиль и перейдите на его идентификатор. Затем удалите старый.

client = anthropic.Anthropic()

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

print(deleted.id)

Ответ повторяет идентификатор с "type": "user_profile_deleted". Если удаление возвращает ошибку сервера, повторите его. Код 404 при повторной попытке означает, что первое удаление прошло успешно.

После удаления конечные точки профилей возвращают 404 для этого идентификатора. В течение примерно 10 минут запросы инференса, содержащие удалённый идентификатор, ещё могут выполняться успешно. После этого платформы, проверяющие идентификатор в каждом запросе, отклоняют запрос с кодом 400. Claude in Amazon Bedrock и Google Cloud не ищут профили, поэтому по-прежнему принимают его.

Следующие шаги

В справочнике API приведены поля, типы и ограничения каждой конечной точки: Создание профиля, Получение профиля, Обновление профиля и Список профилей.

Если одобрения программ конечного клиента должны применяться, когда он использует Claude через вашу платформу, см. Отправка конечному клиенту ссылки на Verification Portal.