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

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

Если вы управляете платформой или шлюзом либо перепродаёте доступ к 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=profile_id,
)

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. К таким программам относятся те, для которых одобрена организация конечного клиента, после того как конечный клиент свяжет профиль с этой организацией и, в случае уровней доступа Cyber Verification Program, включит их для профиля на портале.

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(
    profile_id,
    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(profile_id)

print(deleted.id)

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

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

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

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

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

Чтобы получать событие, когда Anthropic ограничивает или блокирует одного из ваших конечных клиентов либо когда ограничение или блокировка завершается, см. Вебхуки организации.