Perfis de usuário para atribuição a clientes finais

Os "user profiles" (perfis de usuário, ou "perfis") informam à Anthropic para qual dos seus clientes finais cada solicitação de API se destina. Assim, uma ação de aplicação de segurança, como uma retenção ou um bloqueio, pode se aplicar a um único cliente final em vez de a toda a sua organização. Quando isso acontece, o restante do seu tráfego não é afetado.

Se você opera uma plataforma ou um gateway, ou revende acesso à API, as solicitações que você envia em nome dos seus clientes finais chegam sob a sua organização. A Anthropic executa classificadores de segurança automatizados sobre o tráfego da API. Sem um perfil na solicitação, um único cliente final pode acionar uma ação de aplicação que se aplica a toda a sua organização.

Você registra cada cliente final uma vez com POST /v1/user_profiles e armazena o ID uprof_ que ele retorna. Em seguida, você envia esse ID no cabeçalho anthropic-user-profile-id em todas as solicitações que fizer em nome desse cliente final.

Os perfis não são cobrados e não afetam os preços.

Decidir quem recebe um perfil

O que um perfil representa depende de como você vende o Claude: uma pessoa que usa seu produto ou uma empresa para a qual você revende acesso à API. Esses dois casos cobrem a maioria das plataformas. O campo access_type do perfil indica qual deles se aplica.

O que um perfil contém e como a Anthropic o usa

Um perfil contém apenas o que você envia sobre o cliente final, além de qualquer status de programa que a Anthropic defina. Ele não contém conteúdo de conversas. A Anthropic usa os detalhes que você envia para atribuir solicitações, monitorar abusos, aplicar a Política de Uso e permitir a candidatura e o acesso a programas de acesso confiável. A Anthropic não verifica os detalhes.

A Anthropic processa os perfis de acordo com a Política de Privacidade.

Antes de começar

Você cria e gerencia perfis em um dos seguintes locais:

• Uma organização na Claude API.
• Uma organização no Claude Platform on AWS. O principal que faz a chamada precisa das ações de IAM de perfil de usuário.
• Uma implantação do Microsoft Foundry hospedada na Anthropic, não uma hospedada no Azure. Você não precisa de uma organização na Claude API nem no Claude Platform on AWS. Use seu endpoint do Foundry, com a mesma URL base e a mesma autenticação que você usa para inferência.

O Amazon Bedrock e o Google Cloud não têm os endpoints /v1/user_profiles. Se sua inferência é executada neles, crie seus perfis em uma organização na Claude API ou no Claude Platform on AWS. No Amazon Bedrock, os perfis funcionam apenas com o Claude no Amazon Bedrock. Consulte Atribuir solicitações no Amazon Bedrock e no Google Cloud.

Mantenha o tráfego que você envia em nome dos seus clientes finais em uma organização e seu próprio uso interno em outra. Os perfis pertencem a uma organização, não a um workspace, então workspaces separados em uma mesma organização não são suficientes. Apenas a organização do tráfego de clientes finais precisa de perfis de usuário. Para criar outra organização na Claude API, consulte a seção "How to create a new organization" de Creating and managing Workspaces in the Claude Console na Central de Ajuda do Claude.

Os exemplos chamam a Claude API com uma chave de API. Você não precisa de uma chave de Admin API. No Claude Platform on AWS, use a URL base e a autenticação dele.

Criar um perfil para cada cliente final

Crie um perfil para cada cliente final cujo tráfego você envia ao Claude. Crie-o uma única vez, no seu fluxo de integração de clientes. POST /v1/user_profiles não é idempotente, então cada chamada cria um novo perfil, mesmo quando reference_id corresponde a um existente. Se você já tem clientes finais sem perfis, consulte a orientação sobre como registrar uma base de clientes existente mais adiante nesta seção.

O exemplo a seguir registra uma empresa que compra acesso à API por meio de um gateway, então define access_type como passthrough. Para um perfil application, omita access_type e descreva um único usuário final em name e external_user_details em vez de uma empresa. Decidir quem recebe um perfil compara os dois tipos de acesso.

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)

A resposta é o novo perfil:

{
  "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"
}

Armazene o id no registro do seu cliente e faça com que suas instâncias de serviço o leiam de lá em vez de criarem seu próprio perfil. Você recupera, atualiza e exclui um perfil por esse id. O campo programs é somente leitura, e a atribuição não o utiliza. Ele contém o status do cliente final em cada programa que a Anthropic administra. Para saber o que seus valores significam, consulte quais programas se aplicam a um perfil.

Não há limite para o número de perfis em uma organização, mas a criação de perfis está sujeita a um "rate limit" (limite de taxa). Antes de registrar uma base de clientes existente em massa, entre em contato com sua equipe de conta da Anthropic.

O que informar à Anthropic sobre um cliente final

Todos os campos são opcionais. Você pode enviar name, metadata e estes campos em external_user_details: entity_type, country, reference_id, onboarded_at, account_status, name_hash e email_hash. A referência Criar um perfil descreve cada campo, com seu tipo, formato e limite de tamanho.

Siga estas regras ao definir os campos:

• Valores desconhecidos: Se você não souber um valor, omita-o em vez de enviar um valor fictício. Você pode substituir um valor em external_user_details depois, mas não pode apagá-lo.
• Nomes de empresas: Para um perfil passthrough, envie a razão social da empresa em name, se você a souber.
• País: Em country, envie o país do cliente final, não o seu.
• Seu próprio ID: Em reference_id, envie seu próprio identificador estável para o cliente final. Ele não precisa ser único.
• Nomes e endereços de e-mail que você não pode compartilhar: Omita name e envie external_user_details.name_hash em seu lugar. Para o endereço de e-mail, envie external_user_details.email_hash. Um perfil não tem campo para o endereço em si.
• Hashes: Calcule os hashes você mesmo, com uma função de sua escolha. Eles mostram à Anthropic quais dos seus perfis compartilham um nome ou um endereço de e-mail. Use a mesma função e a mesma normalização de maiúsculas/minúsculas e espaços em branco para todos os perfis, porque apenas valores calculados da mesma forma correspondem.

Atribuir cada solicitação

Envie o ID do perfil no cabeçalho anthropic-user-profile-id em todas as solicitações que você fizer em nome do cliente final. Os SDKs e a CLI têm um argumento que envia o cabeçalho para você: 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)

O cabeçalho funciona da mesma forma em solicitações de contagem de tokens, Message Batches e compatibilidade com o SDK da OpenAI. Em um lote, ele se aplica a todas as solicitações do lote.

A Claude API, o Claude Platform on AWS e as implantações do Microsoft Foundry hospedadas na Anthropic verificam o ID em todas as solicitações. Se o ID estiver malformado ou não pertencer à organização que envia a solicitação, a API retorna um 400 invalid_request_error. Por padrão, essas plataformas aceitam um ID de perfil apenas em solicitações da organização que criou o perfil. Isso significa que, se você envia tráfego sob mais de uma organização, por exemplo uma na Claude API e outra no Claude Platform on AWS, uma solicitação de uma organização que não criou o perfil recebe o mesmo 400.

Message Batches é a exceção: a criação de um lote verifica apenas o formato do ID. Se um ID bem formado não pertencer à organização que envia o lote, o lote ainda é criado, e cada solicitação nele falha com um resultado errored que contém o mesmo invalid_request_error.

Atribuir solicitações no Amazon Bedrock e no Google Cloud

Um ID de perfil de qualquer tipo de acesso também funciona no Claude no Amazon Bedrock e no Google Cloud. Ele não funciona com a integração anterior do Amazon Bedrock que você chama com InvokeModel ou Converse. Você usa as credenciais da sua organização da Anthropic apenas para criar e gerenciar perfis. A inferência continua usando suas credenciais existentes da AWS ou do Google Cloud.

No Claude no Amazon Bedrock, coloque o ID no nível superior do corpo da solicitação:

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

Vincule cada conta da AWS que envia solicitações ao Claude no Amazon Bedrock, e cada projeto do Google Cloud que envia solicitações no Google Cloud, à organização da Anthropic que cria seus perfis:

1. Um administrador ou proprietário dessa organização inicia o vínculo no Verification Portal em portal.anthropic.com, em Linked accounts.
2. Alguém que possa gerenciar o IAM na conta da AWS ou no projeto do Google Cloud executa um comando fornecido pelo portal.
3. O administrador ou proprietário conclui a verificação no portal.

Os programas que se aplicam a um perfil só se aplicam às solicitações de uma conta depois que a conta é vinculada e o portal a mostra como Linked. Esses programas incluem aqueles para os quais a organização de um cliente final é aprovada depois que o cliente final vincula o perfil a essa organização.

O Claude no Amazon Bedrock e o Google Cloud verificam o formato do ID, mas não consultam o perfil. Eles rejeitam um ID malformado com um 400. Eles aceitam qualquer ID bem formado, então uma resposta bem-sucedida não confirma que o ID corresponde a um perfil. Uma solicitação sem ID é processada sem atribuição e, se acionar uma ação de aplicação, a ação se aplica a toda a sua organização.

Identificar usuários individuais dentro de uma empresa

Um perfil passthrough identifica uma empresa, não a pessoa que faz a solicitação. Se uma solicitação vier de uma pessoa identificável, envie também um identificador para essa pessoa no campo metadata.user_id da solicitação de Messages. Esse é o próprio objeto metadata da solicitação, não o campo metadata do perfil. O identificador é opcional e ajuda a Anthropic a detectar uso indevido por uma única pessoa.

Manter os perfis atualizados

Atualize um perfil quando os detalhes ou o status da conta do cliente final mudarem, e exclua-o quando ele encerrar a conta ou pedir que você apague seus dados.

Atualizar um perfil

POST /v1/user_profiles/{id} altera apenas os campos que você envia. Por exemplo, use-o quando uma empresa mudar de marca ou quando você suspender uma conta.

• name e access_type substituem o valor armazenado.
• Cada campo que você envia em external_user_details substitui o valor armazenado. Você não pode apagar um valor. A API rejeita null com um 400.
• metadata é mesclado chave por chave. Uma chave que você envia sobrescreve o valor armazenado, uma string vazia exclui a chave, e as chaves que você omite permanecem como estão.

O exemplo a seguir marca a conta como suspensa e remove uma chave de metadados trial_cohort.

client = anthropic.Anthropic()

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

print(profile)

Excluir um perfil

DELETE /v1/user_profiles/{id} exclui permanentemente um perfil e tudo o que você forneceu para ele, incluindo name, external_user_details e metadata. Isso não remove os registros de confiança e segurança que a Anthropic mantém sobre esse ID de perfil.

Exclua um perfil quando um cliente final encerrar a conta ou pedir que você apague seus dados. Antes de excluir um perfil, pare de enviar seu ID nas solicitações desse cliente final. Se o cliente final continuar com você após uma solicitação de exclusão de dados, crie um novo perfil e passe a usar o ID dele. Em seguida, exclua o antigo.

client = anthropic.Anthropic()

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

print(deleted.id)

A resposta repete o ID com "type": "user_profile_deleted". Se uma exclusão retornar um erro de servidor, tente novamente. Um 404 na nova tentativa significa que a primeira exclusão foi concluída.

Após uma exclusão, os endpoints de perfil retornam um 404 para esse ID. Por até cerca de 10 minutos, solicitações de inferência que carregam o ID excluído ainda podem ser bem-sucedidas. Depois disso, as plataformas que verificam o ID em todas as solicitações rejeitam a solicitação com um 400. O Claude no Amazon Bedrock e o Google Cloud não consultam perfis, então continuam aceitando-a.

Próximos passos

A referência da API traz os campos, tipos e limites de cada endpoint: Criar um perfil, Recuperar um perfil, Atualizar um perfil e Listar perfis.

Se as aprovações de programa de um cliente final devem se aplicar quando ele usa o Claude por meio da sua plataforma, consulte Enviar a um cliente final um link para o Verification Portal.