Profils utilisateur pour l'attribution aux clients finaux

Les « user profiles » (profils utilisateur, ou « profils ») indiquent à Anthropic pour lequel de vos clients finaux chaque requête API est effectuée. Une mesure d'application de sécurité, telle qu'une suspension ou un blocage, peut alors s'appliquer à un seul client final plutôt qu'à l'ensemble de votre organisation. Dans ce cas, le reste de votre trafic n'est pas affecté.

Si vous exploitez une plateforme ou une passerelle, ou si vous revendez un accès à l'API, les requêtes que vous envoyez pour vos clients finaux arrivent sous votre organisation. Anthropic exécute des classificateurs de sécurité automatisés sur le trafic de l'API. Sans profil sur la requête, un seul client final peut déclencher une mesure d'application qui s'applique à l'ensemble de votre organisation.

Vous enregistrez chaque client final une seule fois avec POST /v1/user_profiles et vous stockez l'ID uprof_ qui est renvoyé. Vous envoyez ensuite cet ID dans l'en-tête anthropic-user-profile-id de chaque requête que vous effectuez pour le compte de ce client final.

Les profils ne sont pas facturables et n'affectent pas la tarification.

Décider qui reçoit un profil

Ce que représente un profil dépend de la manière dont vous vendez Claude : une personne qui utilise votre produit, ou une entreprise à laquelle vous revendez un accès à l'API. Ces deux cas couvrent la plupart des plateformes. Le champ access_type du profil indique lequel s'applique.

Ce que contient un profil et comment Anthropic l'utilise

Un profil contient uniquement ce que vous envoyez au sujet du client final, ainsi que tout statut de programme défini par Anthropic. Il ne contient pas le contenu des conversations. Anthropic utilise les informations que vous envoyez pour attribuer les requêtes, pour surveiller les abus, pour faire respecter la Politique d'utilisation, et pour permettre la candidature et l'accès aux programmes d'accès de confiance. Anthropic ne vérifie pas ces informations.

Anthropic traite les profils conformément à la Politique de confidentialité.

Avant de commencer

Vous créez et gérez les profils dans l'un des éléments suivants :

• Une organisation sur l'API Claude.
• Une organisation sur Claude Platform on AWS. Le principal appelant a besoin des actions IAM relatives aux profils utilisateur.
• Un déploiement Microsoft Foundry hébergé sur Anthropic, et non un déploiement hébergé sur Azure. Vous n'avez pas besoin d'une organisation sur l'API Claude ou sur Claude Platform on AWS. Utilisez votre point de terminaison Foundry, avec la même URL de base et la même authentification que celles que vous utilisez pour l'inférence.

Amazon Bedrock et Google Cloud ne disposent pas des points de terminaison /v1/user_profiles. Si votre inférence s'exécute sur ces plateformes, créez vos profils dans une organisation sur l'API Claude ou sur Claude Platform on AWS. Sur Amazon Bedrock, les profils fonctionnent uniquement avec Claude dans Amazon Bedrock. Consultez Attribuer les requêtes sur Amazon Bedrock et Google Cloud.

Conservez le trafic que vous envoyez pour vos clients finaux dans une organisation et votre propre utilisation interne dans une autre. Les profils appartiennent à une organisation, et non à un espace de travail ; des espaces de travail distincts au sein d'une même organisation ne suffisent donc pas. Seule l'organisation destinée au trafic des clients finaux a besoin de profils utilisateur. Pour créer une autre organisation sur l'API Claude, consultez la section « How to create a new organization » de l'article Creating and managing Workspaces in the Claude Console dans le centre d'aide Claude.

Les exemples appellent l'API Claude avec une clé API. Vous n'avez pas besoin d'une clé Admin API. Sur Claude Platform on AWS, utilisez son URL de base et son authentification.

Créer un profil pour chaque client final

Créez un profil pour chaque client final dont vous envoyez le trafic à Claude. Créez-le une seule fois, dans votre processus d'intégration des clients. POST /v1/user_profiles n'est pas idempotent : chaque appel crée donc un nouveau profil, même lorsque reference_id correspond à un profil existant. Si vous avez déjà des clients finaux sans profil, consultez les recommandations sur l'enregistrement d'une base de clients existante plus loin dans cette section.

L'exemple suivant enregistre une entreprise qui achète un accès à l'API via une passerelle ; il définit donc access_type sur passthrough. Pour un profil application, omettez access_type et décrivez un utilisateur final dans name et external_user_details au lieu d'une entreprise. Décider qui reçoit un profil compare les deux types d'accès.

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)

La réponse est le nouveau profil :

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

Stockez l'id dans votre fiche client, et faites en sorte que vos instances de service le lisent à partir de là au lieu de créer leur propre profil. Vous récupérez, mettez à jour et supprimez un profil à l'aide de cet id. Le champ programs est en lecture seule, et l'attribution ne l'utilise pas. Il contient le statut du client final dans chaque programme géré par Anthropic. Pour connaître la signification de ses valeurs, consultez quels programmes s'appliquent à un profil.

Il n'y a pas de plafond au nombre de profils dans une organisation, mais la création de profils est soumise à une « rate limit » (limite de débit). Avant d'enregistrer en masse une base de clients existante, contactez votre équipe de compte Anthropic.

Ce qu'il faut indiquer à Anthropic au sujet d'un client final

Tous les champs sont facultatifs. Vous pouvez envoyer name, metadata, ainsi que les champs suivants dans external_user_details : entity_type, country, reference_id, onboarded_at, account_status, name_hash et email_hash. La référence Créer un profil décrit chaque champ, avec son type, son format et sa limite de longueur.

Respectez les règles suivantes lorsque vous définissez les champs :

• Valeurs inconnues : si vous ne connaissez pas une valeur, omettez-la au lieu d'envoyer une valeur fictive. Vous pouvez remplacer ultérieurement une valeur dans external_user_details, mais vous ne pouvez pas l'effacer.
• Noms d'entreprise : pour un profil passthrough, envoyez la raison sociale de l'entreprise dans name si vous la connaissez.
• Pays : dans country, envoyez le pays du client final, et non le vôtre.
• Votre propre ID : dans reference_id, envoyez votre propre identifiant stable pour le client final. Il n'a pas besoin d'être unique.
• Noms et adresses e-mail que vous ne pouvez pas partager : omettez name et envoyez plutôt external_user_details.name_hash. Pour l'adresse e-mail, envoyez external_user_details.email_hash. Un profil ne comporte aucun champ pour l'adresse elle-même.
• Hachages : calculez les hachages vous-même, avec une fonction de votre choix. Ils indiquent à Anthropic lesquels de vos profils partagent un nom ou une adresse e-mail. Utilisez la même fonction et la même normalisation de la casse et des espaces pour chaque profil, car seules les valeurs calculées de la même manière correspondent.

Attribuer chaque requête

Envoyez l'ID de profil dans l'en-tête anthropic-user-profile-id de chaque requête que vous effectuez pour le compte du client final. Les SDK et la CLI disposent d'un argument qui envoie l'en-tête pour vous : 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)

L'en-tête fonctionne de la même manière sur les requêtes de comptage de tokens, de Message Batches et de compatibilité avec le SDK OpenAI. Sur un lot, il s'applique à chaque requête du lot.

L'API Claude, Claude Platform on AWS et les déploiements Microsoft Foundry hébergés sur Anthropic vérifient l'ID sur chaque requête. Si l'ID est mal formé ou n'appartient pas à l'organisation qui envoie la requête, l'API renvoie une erreur 400 invalid_request_error. Par défaut, ces plateformes n'acceptent un ID de profil que sur les requêtes provenant de l'organisation qui a créé le profil. Cela signifie que si vous envoyez du trafic sous plusieurs organisations, par exemple une sur l'API Claude et une sur Claude Platform on AWS, une requête provenant d'une organisation qui n'a pas créé le profil reçoit la même erreur 400.

Message Batches constitue l'exception : la création d'un lot vérifie uniquement le format de l'ID. Si un ID bien formé n'appartient pas à l'organisation qui envoie le lot, le lot est tout de même créé, et chaque requête qu'il contient échoue ensuite avec un résultat errored contenant la même invalid_request_error.

Attribuer les requêtes sur Amazon Bedrock et Google Cloud

Un ID de profil de l'un ou l'autre type d'accès fonctionne également sur Claude dans Amazon Bedrock et sur Google Cloud. Il ne fonctionne pas avec l'ancienne intégration Amazon Bedrock que vous appelez avec InvokeModel ou Converse. Vous utilisez les identifiants de votre organisation Anthropic uniquement pour créer et gérer les profils. L'inférence continue d'utiliser vos identifiants AWS ou Google Cloud existants.

Sur Claude dans Amazon Bedrock, placez l'ID au niveau supérieur du corps de la requête :

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

Associez chaque compte AWS qui envoie des requêtes à Claude dans Amazon Bedrock, et chaque projet Google Cloud qui envoie des requêtes sur Google Cloud, à l'organisation Anthropic qui crée vos profils :

1. Un administrateur ou un propriétaire de cette organisation lance l'association dans le Verification Portal à l'adresse portal.anthropic.com, sous Linked accounts.
2. Une personne habilitée à gérer IAM dans le compte AWS ou le projet Google Cloud exécute une commande fournie par le portail.
3. L'administrateur ou le propriétaire termine la vérification dans le portail.

Les programmes qui s'appliquent à un profil ne s'appliquent aux requêtes d'un compte qu'une fois le compte associé et affiché comme Linked dans le portail. Ces programmes incluent ceux pour lesquels l'organisation d'un client final est approuvée après que le client final a associé le profil à cette organisation.

Claude dans Amazon Bedrock et Google Cloud vérifient le format de l'ID mais ne recherchent pas le profil. Ils rejettent un ID mal formé avec une erreur 400. Ils acceptent tout ID bien formé ; une réponse réussie ne confirme donc pas que l'ID correspond à un profil. Une requête sans ID est traitée sans attribution, et si elle déclenche une mesure d'application, celle-ci s'applique à l'ensemble de votre organisation.

Identifier les utilisateurs individuels au sein d'une entreprise

Un profil passthrough identifie une entreprise, et non la personne qui effectue la requête. Si une requête provient d'une personne identifiable, envoyez également un identifiant pour cette personne dans le champ metadata.user_id de la requête Messages. Il s'agit de l'objet metadata propre à la requête, et non du champ metadata du profil. L'identifiant est facultatif, et il aide Anthropic à détecter les abus commis par une seule personne.

Maintenir les profils à jour

Mettez à jour un profil lorsque les informations ou le statut du compte du client final changent, et supprimez-le lorsqu'il ferme son compte ou vous demande d'effacer ses données.

Mettre à jour un profil

POST /v1/user_profiles/{id} modifie uniquement les champs que vous envoyez. Utilisez-le par exemple lorsqu'une entreprise change de marque ou lorsque vous suspendez un compte.

• name et access_type remplacent la valeur stockée.
• Chaque champ que vous envoyez dans external_user_details remplace la valeur stockée. Vous ne pouvez pas effacer une valeur. L'API rejette null avec une erreur 400.
• metadata est fusionné clé par clé. Une clé que vous envoyez écrase la valeur stockée, une chaîne vide supprime la clé, et les clés que vous omettez restent inchangées.

L'exemple suivant marque le compte comme suspendu et supprime une clé de métadonnées trial_cohort.

client = anthropic.Anthropic()

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

print(profile)

Supprimer un profil

DELETE /v1/user_profiles/{id} supprime définitivement un profil et tout ce que vous avez fourni pour celui-ci, y compris name, external_user_details et metadata. Cela ne supprime pas les enregistrements de confiance et de sécurité qu'Anthropic conserve au sujet de cet ID de profil.

Supprimez un profil lorsqu'un client final ferme son compte ou vous demande d'effacer ses données. Avant de supprimer un profil, cessez d'envoyer son ID sur les requêtes de ce client final. Si le client final reste chez vous après une demande d'effacement, créez un nouveau profil et passez à son ID. Supprimez ensuite l'ancien.

client = anthropic.Anthropic()

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

print(deleted.id)

La réponse reprend l'ID avec "type": "user_profile_deleted". Si une suppression renvoie une erreur serveur, réessayez-la. Une erreur 404 lors de la nouvelle tentative signifie que la première suppression a abouti.

Après une suppression, les points de terminaison des profils renvoient une erreur 404 pour cet ID. Pendant environ 10 minutes au maximum, les requêtes d'inférence qui portent l'ID supprimé peuvent encore réussir. Passé ce délai, les plateformes qui vérifient l'ID sur chaque requête rejettent la requête avec une erreur 400. Claude dans Amazon Bedrock et Google Cloud ne recherchent pas les profils ; ils continuent donc de l'accepter.

Étapes suivantes

La référence de l'API présente les champs, les types et les limites de chaque point de terminaison : Créer un profil, Récupérer un profil, Mettre à jour un profil et Lister les profils.

Si les approbations de programme d'un client final doivent s'appliquer lorsqu'il utilise Claude via votre plateforme, consultez Envoyer à un client final un lien vers le Verification Portal.