Claude Platform Docs
AdministrationClaude Platform OAuth

Linked billing

Permettez à vos clients de lier leur organisation Claude Platform à votre application avec OAuth, et facturez l’utilisation de Claude à l’organisation du client.

Linked billing permet à vos clients de payer l’utilisation de Claude dans votre application via leur propre organisation Claude. Un client lie son organisation Claude à votre application une seule fois. L’API appelle ce lien une « connection » (connexion). Une fois que le client a effectué la liaison, vous choisissez pour chaque requête à l’API Claude si c’est le client ou vous qui payez. Le client peut dissocier votre application à tout moment. Si une requête que vous marquez pour le client ne peut pas lui être facturée, l’API Claude la refuse plutôt que de vous la facturer.

Ce guide s’adresse aux développeurs dont les utilisateurs d’application sont principalement des clients de la Claude Platform. Vous ajoutez un bouton « Link your Claude organization » à votre application. Votre utilisateur clique dessus, se connecte à Claude et autorise votre application à facturer son organisation Claude pour les requêtes à l’API Claude que le client vous demande d’effectuer. Votre application ajoute ensuite un champ billing_policy aux requêtes que le client paie.

Clients et points de terminaison éligibles

Clients éligibles : un client ne peut être facturé de cette manière que si son organisation Claude Platform paie directement Anthropic pour son utilisation de l’API. Les crédits prépayés et le paiement par facture sont tous deux acceptés. Les organisations facturées via une place de marché cloud (AWS, Google Cloud ou Azure) ne peuvent pas être facturées via cette intégration. Il en va de même pour les organisations qui ne disposent que d’un forfait d’abonnement Claude. Les requêtes les concernant sont refusées avec 403 user_profile_not_billable.

Les requêtes s’exécutent dans votre organisation ; ce sont donc vos « rate limits » (limites de débit), votre accès aux modèles, votre niveau de service, votre conservation des données et vos clés de chiffrement qui s’appliquent. Les propres dispositions de votre client en matière de données ne s’appliquent pas à ces requêtes, notamment la « zero data retention » (conservation zéro des données), ou ZDR, un « business associate agreement » (accord de partenaire commercial), ou BAA, et les « customer-managed encryption keys » (clés de chiffrement gérées par le client), ou CMEK. Ne liez pas de clients qui ont besoin d’une couverture HIPAA, FERPA ou CMEK pour cette utilisation.

Points de terminaison pris en charge : billing_policy est pris en charge sur :

  • /v1/messages
    • Limitation connue : une requête qui facture votre client (bill_to: "user_profile") ne peut pas utiliser les fonctionnalités d’exécution de code facturables (l’API renvoie une erreur 400) ; envoyez donc ces requêtes avec bill_to: "self" ou sans billing_policy.
  • /v1/chat/completions
  • /v1/messages/count_tokens accepte le champ billing_policy et l’ignore, afin que vous puissiez compter les tokens sur le corps exact que vous êtes sur le point d’envoyer.

Message Batches (/v1/messages/batches) ne prend actuellement pas en charge la facturation de votre client. Envoyez les requêtes d’un lot avec bill_to: "self" ou sans billing_policy, et elles vous sont facturées comme d’habitude. Une requête d’un lot qui définit bill_to: "user_profile" est refusée : son résultat est errored avec une invalid_request_error, ni vous ni votre client n’êtes facturés pour celle-ci, et les autres requêtes du lot s’exécutent comme d’habitude.

Pour demander la prise en charge d’un autre point de terminaison, contactez votre équipe de compte Anthropic.

Quels crédits peuvent payer

Tous les crédits ne peuvent pas payer une requête qu’une plateforme facture à un client. Ce qui peut payer dépend de l’organisation facturée : le client si vous facturez un client, ou votre organisation si une plateforme vous facture.

Le crédit acheté dans la Claude Console pour cette organisation peut payer ces requêtes. Si cette organisation utilise le paiement par facture, elle est facturée pour ces requêtes.

Certains crédits promotionnels d’Anthropic ne peuvent pas payer ces requêtes. Ils incluent les crédits API mensuels fournis avec les forfaits Claude Max, Ultra et Team. Les crédits issus des programmes partenaires, VC et startups d’Anthropic ne sont pas éligibles au paiement de ces requêtes.

Lorsque rien sur le compte de cette organisation ne peut payer une requête, l’API Claude peut la refuser avec une erreur 402. La réponse n’indique pas si le refus est dû à un manque de crédit ou à une limite de dépenses. Consultez Erreurs attendues.

Processus de configuration

Vous effectuez ces trois étapes une seule fois. Elles enregistrent votre application auprès d’Anthropic. Ensuite, Quel profil utilisateur lier explique une règle que vous devez connaître avant de créer des profils utilisateur.

Étape 1 : Créer l’application

Créez l’application OAuth dans la Claude Console. Il s’agit de l’enregistrement qui identifie votre produit auprès d’Anthropic : il associe votre URI de redirection à un ID client, et son nom est ce que votre utilisateur voit sur la page d’approbation.

Un membre de votre organisation disposant du rôle Admin ouvre la page Applications OAuth dans la Console et clique sur Créer. Saisissez le nom de votre application et l’URI de redirection (l’adresse de votre application vers laquelle le navigateur revient après l’approbation). Sous What the app can do, sélectionnez Bill and link to organizations.

La page de la nouvelle application s’ouvre. Copiez l’ID client que la Console affiche pour l’application. Votre application l’envoie à l’étape 5 lorsqu’elle demande une page d’approbation, à l’étape 6 lorsqu’elle redirige le navigateur et à l’étape 8 lorsqu’elle échange le code, afin qu’Anthropic sache quelle application fait la demande. L’ID client est public. Dans l’onglet Apparence, définissez le nom, la page d’accueil et l’URL du logo de votre application.

Dans l’onglet Paramètres, Who can link indique Test users only pour une nouvelle application, qui démarre en mode test. Une fois que vous avez publié votre application et qu’elle est en ligne, le paramètre indique Any Claude user.

Étape 2 : Configurer l’authentification du client

Configurez la manière dont votre back-end prouve à auth.claude.com que ses requêtes proviennent de votre application. Cela remplace un secret client : Anthropic n’émet pas de secrets client pour les applications OAuth.

Dans l’onglet Client authentication de l’application, sélectionnez votre Fournisseur d’identité (l’émetteur qui signe les jetons de votre back-end). Pour en ajouter un, cliquez sur Register a new issuer. Définissez ensuite un Motif de l’objet, ou des conditions de revendication sous Options de correspondance avancées, auxquels ces jetons doivent correspondre. Après l’enregistrement, l’onglet affiche l’audience attendue. La revendication aud de votre « client assertion » (assertion client) doit correspondre exactement à cette valeur.

Étape 3 : Configurer l’identité de votre back-end

Votre back-end a besoin de sa propre identité pour appeler l’API Claude. Créez deux éléments :

  • Un « service account » (compte de service). Il s’agit d’un compte non humain de votre organisation Claude. Votre back-end s’authentifie en tant que ce compte lorsqu’il appelle l’API Claude.
  • Une seconde règle de fédération. Semblable à la règle d’authentification client de l’application à l’étape 2, elle permet à votre back-end de s’authentifier avec des jetons de votre propre fournisseur d’identité.

Pour les configurer dans la Claude Console, suivez le guide Workload Identity Federation.

Ensuite, dans l’onglet Client authentication de l’application, sélectionnez ce compte de service comme compte de service opérateur de l’application. Seul ce compte de service est autorisé à envoyer des requêtes d’inférence et à attribuer la facturation aux profils utilisateur liés. Un compte de service ne peut être l’opérateur que d’une seule application OAuth.

Par défaut, toute requête authentifiée en tant que ce compte de service peut facturer chaque client lié, en définissant l’en-tête de profil utilisateur et bill_to dans l’API Messages. Pour obtenir des jetons d’authentification limités à une connexion spécifique, consultez Jetons OAuth pour chaque connexion. Avant de lier des clients, définissez un espace de travail pour votre application. L’étape 8 renvoie un tel jeton pour chaque client, et exige que l’application spécifie un espace de travail par défaut de votre organisation dans lequel s’exécute l’inférence. Si vous souhaitez des « refresh tokens » (jetons d’actualisation) pour chaque connexion, activez également Offline access pour votre application. Demandez ensuite offline_access dans le flux d’autorisation, à l’étape 5, avant de lier des clients.

Un « user profile » (profil utilisateur) est un enregistrement dans votre propre organisation Claude qui représente l’un de vos clients. Chaque requête qui facture le client inclut l’ID du profil, afin qu’Anthropic sache quel client facturer. Pour tout ce que font par ailleurs les profils, consultez Profils utilisateur pour l’attribution aux clients finaux.

Déterminez quel profil utilisateur représente chaque client avant de lier votre premier client. Au sein d’une même application, les connexions sont en correspondance un à un :

  • L’organisation Claude d’un client ne peut être liée qu’à un seul de vos profils utilisateur.
  • Un profil utilisateur ne peut être lié qu’à une seule organisation Claude.

L’organisation Claude du client est celle que l’utilisateur sélectionne lorsqu’il approuve votre application. Pour savoir comment les équipes d’un client utilisent les organisations Claude, demandez-le au client. Pour appliquer la règle de correspondance un à un à vos enregistrements clients :

  • Plusieurs équipes d’un même client partagent une organisation Claude : utilisez un seul profil utilisateur pour toutes les équipes.
  • Chaque équipe possède sa propre organisation Claude : créez un profil utilisateur pour chaque organisation.

Tout profil utilisateur actif de votre organisation peut être lié, tant que la règle de correspondance un à un est respectée. La liaison ne modifie pas le profil, son ID ni son historique d’utilisation. Si vous liez un second profil utilisateur à une organisation Claude déjà liée, l’approbation est refusée : consultez user_profile_already_linked.

Un profil utilisateur pour chaque personne

Vous disposez peut-être déjà d’un profil utilisateur pour chaque personne qui utilise votre produit. Plusieurs de ces personnes peuvent travailler pour un même client. Dans ce cas, Anthropic vous recommande de créer un profil utilisateur supplémentaire pour l’organisation Claude du client, et de lier ce profil.

L’ID de profil à envoyer dépend de qui paie la requête :

  • Requêtes que vous facturez au client : envoyez l’ID du profil du client. Pour identifier également la personne sur une requête /v1/messages, définissez metadata.user_idAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. sur un identifiant la concernant. Cet identifiant est facultatif, et il aide Anthropic à détecter les abus commis par une personne. Utilisez une valeur opaque, et non un nom, une adresse e-mail ou un numéro de téléphone.
  • Requêtes que vous payez : vous pouvez continuer d’envoyer l’ID du profil propre à la personne.

Lier chaque client

Vous effectuez les étapes 4 à 8 pour chaque client qui lie son organisation. Les extraits de code Python suivants nécessitent le SDK Anthropic et quelques imports standard ; consultez Initialisation des extraits de code. Les exemples dans les autres langages et la CLI récupèrent leurs identifiants depuis l’environnement. Assurez-vous que ANTHROPIC_API_KEY n’est pas définie, car votre application doit s’authentifier avec Workload Identity Federation.

Ajoutez un bouton « Link your Claude organization » à l’endroit où vos clients gèrent la facturation ou les intégrations dans votre produit (pour le HTML, les couleurs et le logo du bouton, consultez Exemples de marque). Indiquez-leur que, pour effectuer la liaison, ils doivent disposer du rôle Admin ou Facturation dans leur organisation Claude.

Pour effectuer d’abord les étapes vous-même, consultez Tester en tant que client.

Navigateur
Votre back-end
auth.claude.com
Cliquer sur « ⁠Link your Claude organization ⁠»
5
Requête d'autorisation poussée avec l'ID du profil utilisateur et une assertion client
request_uri
6
Rediriger vers la page d'approbation (le point de terminaison d'autorisation)
7
L'utilisateur se connecte à Claude, choisit l'organisation et approuve
Rediriger vers votre URI de redirection avec un code à usage unique et le state
Transmettre le code et le state
Vérifier que le state correspond
8
Requête de jeton avec le code, le vérificateur de code PKCE et une assertion client
connection_id
Stocker l'ID de connexion dans la fiche du client

Étape 4 : Créer un profil utilisateur pour le client

Créez un profil utilisateur pour l’organisation Claude de chaque client, et stockez l’ID du profil dans l’enregistrement du client dans votre produit.

Si vous disposez déjà d’un profil utilisateur pour l’organisation Claude de ce client, ignorez cette étape et utilisez l’ID de ce profil. Pour déterminer de quel profil il s’agit, consultez Quel profil utilisateur lier.

def create_user_profile(name: str, customer_id: str) -> str:
    profile = client.user_profiles.create(
        name=name,
        external_user_details={"reference_id": customer_id},
    )
    return profile.id  # "uprof_..."


user_profile_id = create_user_profile("Example Customer Inc.", "your-customer-id-123")

Si votre organisation revend l’accès à l’API, envoyez également "access_type": "passthrough" lorsque vous créez ce profil. Ces exemples omettent access_type, ce qui crée un profil application. Pour les deux types, consultez Décider qui obtient un profil.

La réponse contient l’id du profil, par exemple uprof_01HV9Z.

Étape 5 : Créer une URL de requête d’autorisation poussée

Créez une « pushed authorization request » (requête d’autorisation poussée) faisant référence au profil utilisateur du client de l’étape 4. La réponse vous fournit un request_uri. À l’étape suivante, vous l’utilisez pour rediriger votre utilisateur vers la page d’approbation.

Avant d’envoyer la requête, votre back-end crée deux valeurs aléatoires et les stocke dans la session du navigateur et dans l’enregistrement du client. Il les réutilise toutes les deux à l’étape 8 :

  • Une valeur state, qui vous permet de vérifier que le navigateur qui revient vers votre application est bien celui qui a lancé cette requête.
  • Un vérificateur de code PKCE, un secret connu uniquement de votre back-end. La requête en transporte un hachage (le défi de code), et l’étape 8 envoie le vérificateur lui-même, de sorte que seul votre back-end puisse utiliser le code renvoyé.
def push_authorization_request(user_profile_id: str) -> dict:
    state = secrets.token_urlsafe(32)
    code_verifier = secrets.token_urlsafe(64)
    code_challenge = create_s256_code_challenge(code_verifier)

    response = httpx.post(
        f"{AUTH}/v1/oauth/par",
        json={
            "response_type": "code",
            "client_id": CLIENT_ID,
            "redirect_uri": REDIRECT_URI,
            "scope": "billing:attribution",
            "connection_type": "organization_shared",
            "connection_auth_target": "platform",
            "user_profile_id": user_profile_id,
            "state": state,
            "code_challenge": code_challenge,
            "code_challenge_method": "S256",
            "client_assertion_type": JWT_BEARER,
            "client_assertion": client_assertion(),
        },
    )
    response.raise_for_status()  # on an error, do not redirect the browser

    return {
        "state": state,
        "code_verifier": code_verifier,
        "request_uri": response.json()["request_uri"],  # valid for 600 seconds
        "user_profile_id": user_profile_id,
    }


par = push_authorization_request(user_profile_id)

auth.claude.com répond avec un HTTP 201, un request_uri et un expires_in de 600 secondes. Le request_uri identifie la page d’approbation pour cette requête. Le scope doit être exactement billing:attribution ou billing:attribution offline_access. Consultez Portées pour une connexion de facturation pour plus de détails. Les exemples envoient billing:attribution. Si votre application ne dispose pas de cette portée, ajoutez-la sous Billing dans l’onglet Permissions de l’application.

connection_auth_target doit être platform : les requêtes d’inférence s’exécutent dans votre propre organisation et s’authentifient en tant que compte de service opérateur, mais elles peuvent facturer le client.

user_profile_id doit être l’ID d’un profil utilisateur actif de votre organisation. Si la requête d’autorisation poussée échoue, auth.claude.com renvoie une réponse d’erreur OAuth à votre back-end. Ne redirigez pas le navigateur dans ce cas.

Étape 6 : Envoyer votre utilisateur vers la page d’approbation Claude

Tout d’abord, indiquez à votre utilisateur quel compte de votre produit il est en train de lier, et demandez-lui de vérifier le compte Claude affiché sur la page d’approbation. La page indique quel compte Claude est connecté et permet à l’utilisateur de passer à un autre. La page d’approbation ne propose que les organisations du compte Claude connecté dans le navigateur ; le mauvais compte peut donc lier la mauvaise organisation. C’est l’organisation que l’utilisateur lie qui paie.

Ensuite, redirigez votre utilisateur vers le point de terminaison d’autorisation, qui affiche une page d’approbation. Incluez uniquement votre client_id et le request_uri de l’étape 5.

def authorize_url(par: dict) -> str:
    query = urlencode({"client_id": CLIENT_ID, "request_uri": par["request_uri"]})
    return f"{AUTH}/oauth/authorize?{query}"


redirect_to = authorize_url(par)  # answer the click with a 302 to this URL

Étape 7 : L’utilisateur approuve

Votre application n’effectue aucune action à cette étape. L’utilisateur suit ces étapes sur auth.claude.com :

  1. L’utilisateur se connecte à Claude, sauf si le navigateur est déjà connecté.
  2. La page d’approbation affiche les écrans suivants, chacun avec le nom de votre application. Pour savoir ce que fait l’utilisateur sur chaque écran, consultez Liaison.
    1. Select an organization, uniquement si l’utilisateur a le choix entre plusieurs organisations.
    2. How billing works.
    3. Set a monthly spend limit.
    4. Un dernier écran comportant un bouton Link and authorize.
  3. Lorsque l’utilisateur clique sur Link and authorize, auth.claude.com renvoie le navigateur vers votre application. La page d’approbation n’affiche aucun écran de confirmation.

Si l’utilisateur annule ou ne peut pas approuver, aucune connexion n’est établie : consultez Si la liaison n’aboutit pas.

Étape 8 : Gérer le callback et enregistrer la connexion

Après l’approbation, auth.claude.com renvoie le navigateur vers votre URI de redirection avec un code à usage unique et votre valeur state. Cette requête vers votre URI de redirection est appelée le « callback » (rappel). Votre back-end échange le code contre un ID de connexion et le stocke dans l’enregistrement du client. La connexion est ainsi établie. Le callback peut contenir un paramètre error et aucun code. Aucune connexion n’a alors été établie : consultez Si la liaison n’aboutit pas.

Vérifiez que le state correspond à la valeur que vous avez stockée à l’étape 5, puis échangez immédiatement le code depuis votre back-end, avec le vérificateur de code PKCE. Le code est à usage unique et expire au bout de 5 minutes.

def handle_callback(par: dict, params: dict) -> str:
    if not secrets.compare_digest(
        params.get("state", "").encode(), par["state"].encode()
    ):
        raise ValueError("state does not match")
    if "error" in params:  # for example access_denied
        raise PermissionError(params["error"])
    code = params["code"]  # single-use, expires after 5 minutes
    response = httpx.post(
        f"{AUTH}/v1/oauth/token",
        json={
            "grant_type": "authorization_code",
            "code": code,
            "code_verifier": par["code_verifier"],
            "redirect_uri": REDIRECT_URI,
            "client_id": CLIENT_ID,
            "client_assertion_type": JWT_BEARER,
            "client_assertion": client_assertion(),
        },
        timeout=10,  # a response that times out loses the tokens in it
    )
    response.raise_for_status()
    tokens = response.json()
    # Pour utiliser les jetons de la connexion, stockez tokens["access_token"], son expiration
    # (d'après tokens["expires_in"]) et, avec offline_access,
    # tokens["refresh_token"] comme secrets ici : le code ne peut pas être rééchangé.
    # "ocon_..." ; stockez-le dans la fiche client
    return tokens["connection_id"]

La réponse contient l’ID de connexion et le jeton d’accès de la connexion, qui peut authentifier et facturer le client qui a approuvé. Si le client a approuvé offline_access, la réponse contient également un jeton d’actualisation. Stockez dès maintenant le connection_id et les jetons : l’échange ne renvoie les jetons qu’une seule fois. Stocker les jetons décrit la réponse.

Les exemples de cette page qui appellent l’API Claude s’authentifient en tant que compte de service de l’étape 3, et non avec un jeton de cette réponse. Appeler Claude avec le jeton d’accès d’une connexion explique comment utiliser le jeton à sa place.

La réponse n’identifie pas l’organisation Claude que l’utilisateur a liée.

Une connexion terminée ne garantit pas qu’Anthropic puisse facturer le client. Par exemple, l’organisation du client peut ne pas faire partie des clients éligibles. Consultez Mettre à jour les appels à Claude et Erreurs attendues pour savoir comment l’API Claude le vérifie. En raison de cette vérification, formulez votre message de réussite comme « lié » plutôt que « facturation active ».

Si l’échange est refusé avec unauthorized_client, consultez L’échange du code renvoie unauthorized_client.

Tester en tant que client

Pour vérifier que la liaison fonctionne, liez l’une de vos propres organisations. Vous avez d’abord besoin des éléments suivants :

  • Une seconde organisation Claude qui vous appartient, pour jouer le rôle du client. Vous ne pouvez pas lier votre application à l’organisation qui la possède. La page d’approbation ne propose pas cette organisation. La seconde organisation doit faire partie des clients éligibles.
  • Une personne disposant du rôle Admin ou Facturation dans cette organisation, pour approuver la liaison.
  • Tant que votre application n’est pas en ligne, cette personne doit figurer dans la liste Test users de votre application. La liste se trouve dans l’onglet Paramètres de l’application, sous Who can link. Ajoutez la personne à l’aide de l’adresse e-mail de son compte Claude et cliquez sur Save changes. Tant que votre application est en phase de test indique le plafond de dépenses qui s’applique. Retirer une personne de la liste met fin aux liaisons qu’elle a approuvées.

Effectuez ensuite les étapes 4 à 8, et demandez à cette personne d’approuver à l’étape 7. Une fois la liaison établie, le profil utilisateur affiche Linked sur votre page User profiles dans la Console.

Si la liaison n’aboutit pas

Lorsque l’utilisateur ne termine pas l’approbation, ou que auth.claude.com la refuse, aucune connexion n’est établie. Ces entrées couvrent les résultats propres à Linked billing. Pour toutes les autres erreurs, consultez Erreurs dans la Référence OAuth.

Votre URI de redirection reçoit error=access_denied

La requête contient également votre valeur state. Votre URI de redirection reçoit cette erreur dans des cas tels que les suivants :

  1. L’utilisateur clique sur Cancel sur l’un des écrans d’approbation.
  2. La page d’approbation n’a aucune organisation à proposer à l’utilisateur, et celui-ci clique sur le bouton qui renvoie à votre application. Par exemple :
    • L’utilisateur ne dispose du rôle Admin ou Facturation dans aucune organisation Claude Platform.
    • La seule organisation de l’utilisateur est celle qui possède votre application. Consultez Tester en tant que client.
    • Le profil utilisateur est déjà lié à une autre organisation Claude, et l’utilisateur ne dispose pas du rôle Admin ou Facturation dans cette organisation.
    • Tant que votre application n’est pas en ligne, l’utilisateur ne figure pas dans sa liste Test users.

Dans chacun des cas de cette liste, error_description indique the user declined the request ; vous ne pouvez donc pas l’utiliser pour les distinguer.

Une autre cause se trouve dans les paramètres de votre application. Si votre application est en ligne et que Who can link indique uniquement votre organisation, personne en dehors de votre organisation ne peut lier l’application. Sélectionnez Any Claude user et cliquez sur Save changes.

Indiquez à l’utilisateur que la liaison n’a pas abouti, et ne supposez pas qu’il a refusé. Demandez-lui de vérifier avec quel compte Claude il s’est connecté, ainsi que son rôle dans l’organisation qu’il souhaite lier. Un request_uri ne peut plus être utilisé après que l’utilisateur a annulé ou est revenu ; pour permettre à l’utilisateur de réessayer, recommencez donc à partir de l’étape 5.

Votre application reçoit user_profile_already_linked

L’organisation Claude du client est déjà liée à votre application via un autre de vos profils utilisateur. auth.claude.com demande à l’utilisateur de vous contacter. Si l’utilisateur revient à votre application, votre URI de redirection reçoit error=user_profile_already_linked et votre valeur state. Le point de terminaison de jeton peut également renvoyer cette erreur lorsque vous échangez le code à l’étape 8. Cela se produit, par exemple, lorsque l’organisation a été liée entre-temps via un autre profil utilisateur.

Anthropic ne vous indique pas quelle organisation Claude un client lie ; vous ne pouvez donc pas le voir à l’avance. La requête d’autorisation poussée de l’étape 5 réussit, et auth.claude.com ne refuse la connexion qu’au moment où l’utilisateur approuve.

L’erreur n’indique pas quel profil utilisateur détient la connexion. Le détenteur le plus probable est un autre profil lié de ce client. Anthropic n’indique pas à quelle organisation un profil est lié ; confirmez donc auprès du client avant d’agir. Si ce profil détient la connexion, effectuez l’une des actions suivantes :

  • Sur les requêtes que vous facturez à ce client, envoyez l’ID de ce profil utilisateur.
  • Mettez fin à cette connexion, comme le décrit Dissocier un client, puis effectuez à nouveau les étapes 5 à 8 avec le profil utilisateur qui a été refusé.

Si aucun des profils de ce client n’est lié, l’utilisateur a peut-être sélectionné une organisation appartenant à un autre de vos clients. Recommencez à partir de l’étape 5, et demandez à l’utilisateur de vérifier quelle organisation il sélectionne.

Votre URI de redirection ne reçoit rien

Votre application ne peut pas détecter ces deux cas :

  • L’utilisateur ferme la page d’approbation.
  • Le request_uri a expiré ou a déjà été utilisé. La page d’approbation affiche alors une erreur et ne renvoie pas le navigateur vers votre application.

Si l’utilisateur revient à votre produit sans callback, recommencez à partir de l’étape 5. Un request_uri qui n’a pas été utilisé expire 10 minutes après sa création.

L’échange du code renvoie unauthorized_client

Votre application n’est pas configurée pour cette requête. Pour un problème d’espace de travail, error_description en indique la cause. En cas d’absence de compte de service opérateur, il indique uniquement the client is not registered for this grant. Le refus ne consomme pas le code ; vous pouvez donc échanger à nouveau le même code jusqu’à son expiration. Commencez par vérifier ces points dans la Claude Console :

VérificationEmplacementCorrection
L’application dispose d’un compte de service opérateurOperator service account dans l’onglet Client authentication de l’applicationSélectionnez-en un et cliquez sur Save. L’étape 3 explique comment en configurer un.
L’espace de travail de l’application n’est ni manquant ni archivéConfigurer votre applicationChoisissez un espace de travail. Tant que l’application n’en a pas, l’échange est également refusé avec unauthorized_client.

Un compte de service enregistré peut mettre une minute ou deux à atteindre auth.claude.com ; si l’échange est à nouveau refusé, attendez ce délai et réessayez. Si le code a expiré entre-temps, demandez à l’utilisateur d’approuver à nouveau (étapes 5 à 8). Pour les causes que error_description indique pour les jetons d’une connexion, consultez Stocker les jetons et Actualiser les jetons.

Dans tout autre cas, contactez votre équipe de compte Anthropic. Faites de même si la Console indique que le compte de service n’existe plus.

Publier votre application

Tant que votre application n’est pas en ligne, seules les personnes figurant dans sa liste Test users peuvent la lier ; vos clients ne le peuvent donc pas. Pour publier l’application, cliquez sur Publish app sur la page de l’application dans la Claude Console. Une boîte de dialogue s’ouvre.

  • Si votre organisation utilise le paiement par facture, l’application est en ligne dès que vous confirmez dans cette boîte de dialogue.
  • Sinon, vous prouvez d’abord dans cette boîte de dialogue que vous contrôlez le domaine de l’application, puis Anthropic examine l’application.

La preuve de domaine : le domaine est celui de la page d’accueil de votre application. Chaque URI de redirection doit se trouver sur ce domaine ou sur l’un de ses sous-domaines, à l’exception d’une URI sur localhost, 127.0.0.1 ou [::1]. La preuve est un enregistrement DNS TXT. Les modifications DNS peuvent prendre jusqu’à 48 heures ; commencez donc avant d’avoir besoin que vos clients effectuent la liaison. Si votre organisation a déjà prouvé un domaine qui couvre la page d’accueil et ces URI de redirection, la boîte de dialogue passe l’étape de la preuve. Un domaine prouvé couvre ses sous-domaines.

Vous confirmez à la dernière étape de la boîte de dialogue. Si cette étape affiche une case à cocher pour accepter les Linked Billing Terms, cochez-la. Cliquez ensuite sur Publish app dans la boîte de dialogue.

L’examen : pendant l’examen, le statut de l’application dans la Console indique In review. L’application est en ligne lorsqu’Anthropic l’approuve. Si Anthropic ne l’approuve pas, le statut indique Not approved, et vous ne pouvez pas publier à nouveau l’application vous-même. Pour poser des questions sur la décision, contactez le support.

Sauf si votre organisation utilise le paiement par facture, une modification du nom, du logo, de la page d’accueil ou des URI de redirection d’une application en ligne renvoie l’application en examen. Les clients déjà liés restent liés et conservent le plafond qu’ils ont enregistré. Tant qu’Anthropic n’a pas approuvé la modification, seules les personnes figurant dans la liste Test users peuvent lier l’application.

Mettre à jour les appels à Claude

Envoyez l’en-tête anthropic-user-profile-id à chaque appel à /v1/messages et /v1/chat/completions pour un client lié. Sur une requête que vous facturez au client, la valeur de l’en-tête est l’ID du profil utilisateur qui détient la connexion de ce client. Les appels qui définissent billing_policy doivent également envoyer l’en-tête bêta user-profiles-billing-2026-10-01.

Chaque requête pour un client lié est facturée soit au client, soit à vous, et vous choisissez lequel à chaque requête. Les exemples suivants montrent les deux cas.

Jetons OAuth pour chaque connexion décrit une autre façon d’authentifier les requêtes d’un client : un jeton d’accès qui ne peut facturer que ce client. Sur /v1/messages et /v1/chat/completions, une requête avec un tel jeton ne peut pas vous être facturée. Elle est facturée à ce client, même sans billing_policy ni l’en-tête anthropic-user-profile-id, là où ceux-ci sont facultatifs : consultez la note dans Appeler Claude avec le jeton d’accès d’une connexion. Si elle désigne un autre profil utilisateur ou définit bill_to: "self", elle est refusée. N’utilisez jamais un tel jeton pour une requête que vous payez.

Votre client paie

Ajoutez billing_policy avec bill_to: "user_profile" au corps de la requête, et envoyez l’en-tête bêta de facturation ainsi que l’en-tête de l’ID de profil.

Définissez bill_to: "user_profile" uniquement sur les requêtes que le client vous demande d’effectuer : l’utilisation de Claude que le client et ses utilisateurs génèrent dans votre produit. Ne facturez pas à un client votre propre utilisation, comme les tests, les évaluations ou le travail effectué pour d’autres clients. L’API Claude ne peut pas le vérifier à votre place, c’est donc votre responsabilité.

def message_billed_to_user(user_profile_id: str, prompt: str) -> BetaMessage:
    return client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
        betas=[BILLING_BETA],
        extra_headers={"anthropic-user-profile-id": user_profile_id},
        extra_body={
            "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
        },
    )

Si la requête est refusée, consultez Erreurs attendues.

Vous payez

Pour payer vous-même, soit omettez entièrement billing_policy (auquel cas l’en-tête bêta de facturation est facultatif) :

def message_billed_to_you(user_profile_id: str, prompt: str) -> Message:
    return client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
        user_profile_id=user_profile_id,
    )

soit utilisez bill_to: "self" :

def message_billed_to_self(user_profile_id: str, prompt: str) -> BetaMessage:
    return client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
        betas=[BILLING_BETA],
        extra_headers={"anthropic-user-profile-id": user_profile_id},
        extra_body={"billing_policy": {"type": "billing_policy", "bill_to": "self"}},
    )

Jetons OAuth pour chaque connexion

Votre back-end appelle l’API Claude en tant que compte de service opérateur de votre application (étape 3). Par défaut, toute requête authentifiée en tant que ce compte de service peut facturer chaque client lié, en transmettant un en-tête d’ID de profil utilisateur et en incluant bill_to dans les requêtes à l’API Messages. Ce comportement par défaut est appelé l’« operator-only tokenless authentication » (authentification sans jeton réservée à l’opérateur).

Pour gérer les déploiements à locataire unique de votre produit, ou les environnements sandbox contrôlés par le client, vous pouvez obtenir des jetons OAuth d’accès et d’actualisation liés à une connexion au lieu d’utiliser l’authentification sans jeton réservée à l’opérateur.

Pour chaque connexion, l’échange du code de l’étape 8 renvoie le propre jeton d’accès de cette connexion. Le jeton s’authentifie en tant que votre compte de service opérateur, mais il ne peut facturer que le client de cette connexion. Il expire dans un délai d’une heure.

Pour authentifier chaque connexion séparément :

  • Utilisez l’accès hors ligne. Activez Offline access pour votre application, et demandez offline_access à l’étape 5. Chaque connexion obtient alors également un jeton d’actualisation, que votre back-end utilise pour demander de nouveaux jetons d’accès. Sans lui, le client doit approuver à nouveau pour vous donner un nouveau jeton d’accès : effectuez à nouveau les étapes 5 à 8 avec le même scope.
  • Définissez un espace de travail par défaut. Choisissez un espace de travail de votre organisation dans lequel s’exécutent les requêtes effectuées avec ces jetons.
  • Facultativement, désactivez l’authentification sans jeton réservée à l’opérateur. Par défaut, vous pouvez toujours facturer un client lié en tant que votre compte de service opérateur (en transmettant un en-tête de profil utilisateur et bill_to), même après l’expiration du jeton d’accès du client. Après avoir désactivé l’authentification opérateur seul, chaque requête qui facture un client doit s’authentifier avec le jeton d’accès de ce client.
  • Utilisez billing:attribution. Seule cette portée donne à une connexion ses propres jetons. Vous pouvez toujours facturer un client lié en tant que votre compte de service opérateur, comme avec org:billing_attribution, qui est déprécié. Consultez Portées pour une connexion de facturation.

Configurer votre application

Les requêtes effectuées avec le jeton d’accès d’une connexion s’exécutent dans un espace de travail de votre organisation. Chaque application en a besoin d’un, même si vous n’utilisez pas ces jetons : tant que votre application n’a pas d’espace de travail, l’échange du code de l’étape 8 est refusé avec unauthorized_client.

Un membre de votre organisation disposant du rôle Admin ouvre l’onglet Client authentication de l’application dans la Console. Sous le compte de service opérateur, repérez Default workspace for platform auth mode OAuth tokens (le paramètre connection_token_workspace_id de l’application) et cliquez sur Choose workspace. Sélectionnez un espace de travail dont le compte de service opérateur (étape 3) est membre. L’espace de travail ne doit pas être archivé.

Pour obtenir des jetons d’actualisation, activez Offline access dans l’onglet Permissions de l’application. Une modification des portées de l’application met quelques minutes à atteindre auth.claude.com.

Portées pour une connexion de facturation

À l’étape 5, envoyez scope avec la valeur billing:attribution. Pour obtenir également un « refresh token » (jeton d’actualisation), envoyez billing:attribution offline_access.

Pour modifier les portées d’un client déjà lié, par exemple pour ajouter offline_access, effectuez à nouveau les étapes 5 à 8 avec le profil utilisateur existant du client et la nouvelle scope. Vous n’avez pas besoin de le dissocier au préalable. L’échange du code renvoie un nouveau connection_id, et la nouvelle connexion remplace la précédente. Consultez la note de l’étape 8.

Une application peut disposer à la fois de billing:attribution et de la portée dépréciée org:billing_attribution. Vous ajoutez billing:attribution sous Billing dans l’onglet Permissions de l’application. Si vous y supprimez org:billing_attribution, vous ne pouvez plus l’ajouter à nouveau. Une connexion qu’un client a approuvée avec org:billing_attribution continue de facturer via votre compte de service opérateur jusqu’à ce que la connexion prenne fin ou que vous désactiviez l’authentification opérateur seul.

Stocker les jetons

L’échange du code ne renvoie les jetons qu’une seule fois ; stockez-les donc à l’étape 8. La réponse contient access_token, expires_in (au maximum 1 heure, en secondes) et connection_id. Si le client a approuvé offline_access, elle contient également refresh_token et refresh_token_expires_in. Un jeton d’actualisation dure au maximum 1 an, et une actualisation ne prolonge pas cette durée. Passé ce délai, liez à nouveau le client.

Stockez les jetons et leurs dates d’expiration dans un coffre de secrets que seul le service chargé des actualisations peut lire.

Si l’échange est refusé avec unauthorized_client, error_description en indique la cause, par exemple un espace de travail manquant ou archivé. Le code n’est pas consommé : corrigez la cause, puis envoyez à nouveau le même code avant son expiration.

Appeler Claude avec le jeton d’accès d’une connexion

Envoyez le jeton d’accès de la connexion comme jeton bearer dans l’en-tête Authorization, à la place de l’identifiant propre de votre compte de service opérateur. N’envoyez pas d’en-tête x-api-key. Dans le SDK Anthropic, transmettez le jeton via auth_token, ou définissez la variable d’environnement ANTHROPIC_AUTH_TOKEN.

Sur /v1/messages et /v1/chat/completions, la requête est facturée au client de cette connexion. L’en-tête anthropic-user-profile-id et billing_policy sont facultatifs. Vous n’avez besoin de l’en-tête bêta de facturation qu’avec billing_policy.

Sur ces deux points de terminaison, vous ne pouvez pas payer une requête avec ce jeton. Utilisez le jeton uniquement sur ces deux points de terminaison, sur /v1/messages/count_tokens et sur les points de terminaison Models. Envoyez toutes les autres requêtes, ainsi que toutes les requêtes que vous payez, en tant que votre compte de service opérateur, depuis votre propre back-end. Cela inclut une requête qui utilise les fonctionnalités d’exécution de code facturables, qui ne peut pas être facturée à un client.

L’API Claude refuse ces requêtes :

  • 400 invalid_request_error, sans code d’erreur : la requête désignait un autre profil utilisateur ou définissait bill_to: "self".
  • 403 permission_error, sans code d’erreur : la requête a été envoyée à un point de terminaison Message Batches.
  • 401 authentication_error : le jeton a expiré, une actualisation l’a remplacé, ou sa connexion a pris fin. Après la fin d’une connexion, la réponse peut également être 403 user_profile_not_billable.

Actualiser les jetons

Pour renouveler le jeton d’accès d’une connexion, envoyez son jeton d’actualisation au point de terminaison de jeton, https://auth.claude.com/v1/oauth/token, avec l’authentification client de votre application. N’envoyez pas de paramètre scope.

connection_locks: defaultdict[str, threading.Lock] = defaultdict(threading.Lock)


def error_body(response: httpx.Response) -> dict:
    try:
        body = response.json()
    except ValueError:
        return {}
    return body if isinstance(body, dict) else {}


def is_lost(response: httpx.Response) -> bool:
    """True for a 5xx response that can follow a refresh that took effect."""
    if response.status_code < 500:
        return False
    # Une 503 au format de l'API Claude avec un en-tête retry-after est un refus
    # qui n'utilise pas le jeton d'actualisation. Toute autre réponse 5xx compte comme perdue.
    paused = (
        response.status_code == 503
        and error_body(response).get("type") == "error"
        and "retry-after" in response.headers
    )
    return not paused


def hold_error(connection_id: str, reason: str) -> RefreshOnHold:
    return RefreshOnHold(
        f"Connection {connection_id} is on hold. {reason} Don't send its refresh token"
        ' again: that can end the connection. See "Link a customer again" in the'
        " Linked billing guide."
    )


def refresh_connection(connection_id: str, *, force: bool = False) -> tuple[str, int]:
    """Refreshes the connection if its access token is close to its expiry.

    Returns the current access token and its expiry time in Unix seconds. Call
    this from your schedule, and pass force=True to refresh a token that isn't
    close to its expiry. Raises RefreshOnHold when the refresh token can't be sent
    again, now and on every later call, and httpx.HTTPStatusError for a refusal
    that keeps the refresh token. After RefreshOnHold for a lost refresh, pause
    your schedule. Resume with one connection, and resume the others only after
    that refresh succeeds or gets a 4xx.
    """
    # Ce verrou fonctionne dans un seul processus. Si le service a des réplicas, utilisez un verrou
    # partagé par toutes.
    with connection_locks[connection_id]:
        tokens = load_tokens(connection_id)
        if tokens.on_hold:
            raise hold_error(
                connection_id, "An earlier refresh might have used its refresh token."
            )
        if not force and tokens.expires_at - time.time() > REFRESH_MARGIN_SECONDS:
            return tokens.access_token, tokens.expires_at  # not close to expiry
        request = {
            "grant_type": "refresh_token",
            "refresh_token": tokens.refresh_token,
            "client_id": CLIENT_ID,
            "client_assertion_type": JWT_BEARER,
            "client_assertion": client_assertion(),
        }
        url = f"{AUTH}/v1/oauth/token"
        # Mettez la connexion en attente avant que le jeton d'actualisation ne quitte ce processus.
        # Si le processus s'arrête avant l'enregistrement des nouveaux jetons, l'attente reste.
        save_tokens(connection_id, replace(tokens, on_hold=True))
        issued_at = int(time.time())
        started = time.monotonic()
        # httpx ne réessaie pas seul. N'ajoutez pas de nouvelles tentatives : une tentative tardive met fin à la
        # connexion.
        try:
            response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
            lost = is_lost(response)
        except (httpx.ConnectError, httpx.ConnectTimeout):
            # Aucune connexion établie, le jeton d'actualisation n'a donc jamais quitté ce processus.
            save_tokens(connection_id, tokens)
            raise
        except httpx.TransportError:
            lost = True
        if lost:
            # La première requête a peut-être utilisé le jeton d'actualisation. Une seconde requête
            # n'est sûre que dans la limite ci-dessus, envoyez-en donc une immédiatement ou pas
            # du tout.
            if time.monotonic() - started > SECOND_REQUEST_DEADLINE_SECONDS:
                raise hold_error(connection_id, "A refresh got no usable answer.")
            try:
                response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
            except httpx.TransportError:
                raise hold_error(
                    connection_id, "Two refreshes got no answer."
                ) from None
            if response.status_code != 200:
                # Après toute réponse autre que de nouveaux jetons, impossible de savoir si la
                # première requête a pris effet, et une requête ultérieure n'est pas sûre.
                raise hold_error(connection_id, "The second refresh failed.")
        if error_body(response).get("error") == "invalid_grant":
            # Expiré, déjà utilisé, ou la connexion a pris fin. Le renvoyer
            # peut mettre fin à la connexion.
            raise hold_error(connection_id, "The refresh returned invalid_grant.")
        if response.status_code != 200:
            # Un refus qui conserve le jeton d'actualisation, donc levez l'attente.
            save_tokens(connection_id, tokens)
            response.raise_for_status()
        body = response.json()
        tokens = ConnectionTokens(
            refresh_token=body["refresh_token"],
            access_token=body["access_token"],
            expires_at=issued_at + body["expires_in"],
            refresh_expires_at=issued_at + body["refresh_token_expires_in"],
        )
        # Si l'écriture échoue, réessayez l'écriture. Ne rafraîchissez pas à nouveau.
        for attempt in range(5):
            try:
                save_tokens(connection_id, tokens)
                return tokens.access_token, tokens.expires_at
            except OSError:  # your secret store's error type
                if attempt < 4:
                    time.sleep(2**attempt)
        # Les nouveaux jetons n'existent que dans ce processus, et le jeton d'actualisation stocké
        # est consommé. L'enregistrement stocké est toujours en attente. L'erreur contient les nouveaux
        # jetons, afin que l'appelant puisse les stocker quand le magasin de secrets sera rétabli.
        error = hold_error(
            connection_id,
            "The refresh succeeded, but the new tokens could not be saved.",
        )
        error.new_tokens = tokens
        raise error

La réponse contient un nouvel access_token et un nouveau refresh_token. Le jeton d’actualisation que vous avez envoyé est remplacé : ne l’envoyez plus, sauf dans les cas indiqués dans la liste des échecs ci-dessous. L’ancien jeton d’accès cesse de fonctionner en quelques minutes. Initialisation des extraits de code des jetons OAuth définit les fonctions que l’exemple appelle.

  • Stockez le nouveau jeton d’actualisation avant d’utiliser le nouveau jeton d’accès.
  • Actualisez les jetons de chaque connexion depuis un seul service, une actualisation à la fois. Si le service comporte des réplicas, utilisez un verrou partagé par toutes ces réplicas. Un jeton d’actualisation déjà utilisé qui est reçu à nouveau plus de 30 secondes après sa première utilisation met fin à la connexion. Tous les jetons sont révoqués, le client s’affiche comme Unlinked, et aucun identifiant ne peut le facturer tant qu’il n’a pas effectué à nouveau la liaison.
  • Désactivez les nouvelles tentatives automatiques pour la requête d’actualisation, dans votre client HTTP et dans tout proxy.

Si la première requête avec un jeton d’actualisation échoue :

  • La requête n’a pas pu se connecter : le jeton d’actualisation n’a pas été envoyé. Réessayez plus tard.
  • Une connexion interrompue, ou toute réponse 5xx autre que la 503 de cette liste : vous ne pouvez pas savoir si la requête a pris effet ; envoyez donc une nouvelle fois le même jeton d’actualisation.
    1. Envoyez-le immédiatement, et uniquement si moins de 30 secondes se sont écoulées depuis l’envoi de la première requête.
    2. Si cette requête renvoie de nouveaux jetons, stockez-les et n’utilisez qu’eux. Si la première requête a bien pris effet, ses jetons, qui ne vous sont jamais parvenus, sont révoqués.
    3. Si elle renvoie autre chose ou n’obtient aucune réponse, ou si les 30 secondes sont écoulées, n’envoyez pas à nouveau ce jeton d’actualisation. Cessez d’actualiser cette connexion et liez à nouveau le client.
  • Un dépassement de délai : la requête est peut-être toujours en cours d’exécution. N’envoyez pas à nouveau ce jeton d’actualisation. Cessez d’actualiser cette connexion et liez à nouveau le client.
  • 429, ou 503 avec un en-tête retry-after et "type": "error" au niveau supérieur de son corps : rien n’est révoqué. Attendez au moins la durée indiquée par l’en-tête, puis envoyez à nouveau le même jeton d’actualisation.
  • unauthorized_client ou invalid_client : rien n’est révoqué. error_description en indique la cause, par exemple un espace de travail manquant, offline_access qui n’est plus enregistrée pour votre application, ou une assertion client en échec. Corrigez-la, puis envoyez à nouveau le même jeton d’actualisation.
  • invalid_scope : la requête a envoyé un paramètre scope, ou billing:attribution n’est plus enregistrée pour votre application. Rien n’est révoqué. Corrigez la cause, puis envoyez à nouveau le même jeton d’actualisation.
  • invalid_grant : le jeton d’actualisation a expiré ou a déjà été utilisé, la connexion a pris fin, ou l’organisation du client est suspendue. Cessez d’actualiser cette connexion et suivez Lier à nouveau un client, qui commence par une vérification de suspension.

Si une connexion interrompue, une réponse 5xx ou un dépassement de délai vous a conduit à cesser d’actualiser une connexion, suspendez également les actualisations de vos autres connexions. Lorsque vous reprenez, actualisez d’abord une seule connexion, et ne reprenez les autres qu’une fois que cette actualisation a réussi ou a reçu une réponse 4xx.

Exécuter un agent dans un bac à sable

Ne donnez à un « sandbox » (bac à sable) que le jeton d’accès, jamais le jeton d’actualisation. Votre back-end effectue les actualisations et envoie chaque nouveau jeton d’accès au bac à sable. Il détermine quel client un bac à sable sert à partir de l’identité propre du bac à sable, par exemple l’identité de son pod, et jamais à partir d’une valeur que le bac à sable envoie. Il n’envoie à un bac à sable que le jeton de ce client. Le bac à sable ne doit pas pouvoir obtenir un JWT correspondant à l’une de vos règles de fédération ou à l’authentification client de votre application. Ne lui donnez aucun jeton d’identité monté ni aucun accès à un serveur de métadonnées cloud.

Claude Code, le Claude Agent SDK et le SDK Anthropic peuvent lire le jeton depuis un fichier d’identifiants dans un profil de configuration (consultez Fichier de configuration de profil). Dans le bac à sable, créez un répertoire de configuration contenant ce profil. N’y ajoutez pas de client_id : en sa présence, le SDK tente d’actualiser lui-même le jeton.

configs/customer.json
{
  "version": "1.0",
  "authentication": {
    "type": "user_oauth"
  }
}

Écrivez le jeton d’accès dans credentials/customer.json dans le même répertoire, avant le démarrage de l’agent et après chaque actualisation. expires_at est la date d’expiration en secondes Unix. Écrivez un nouveau fichier avec le mode 0600, puis renommez-le pour remplacer l’ancien :

credentials/customer.json
{
  "type": "oauth_token",
  "access_token": "sk-ant-oat01-...",
  "expires_at": 1793635200
}

Définissez ANTHROPIC_CONFIG_DIR sur le répertoire de configuration et ANTHROPIC_PROFILE sur customer. Supprimez tous les autres identifiants dans le bac à sable, comme ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN et le paramètre apiKeyHelper de Claude Code, car chacun peut prendre le pas sur le profil. L’agent relit le fichier au cours des 2 dernières minutes avant expires_at, ainsi qu’après une réponse 401.

def write_credentials_file(
    config_dir: Path, profile: str, token: str, expires_at: int
) -> None:
    credentials_dir = config_dir / "credentials"
    credentials_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
    body = {"type": "oauth_token", "access_token": token, "expires_at": expires_at}
    # Renommez un fichier terminé à sa place, afin que l'agent ne lise jamais un fichier à moitié écrit.
    # mkstemp définit le mode 0600 avec l'utilisateur courant comme propriétaire, exécutez donc ceci en tant qu'
    # utilisateur de l'agent.
    handle, temporary_path = tempfile.mkstemp(dir=credentials_dir)
    with os.fdopen(handle, "w") as temporary_file:
        json.dump(body, temporary_file)
    os.replace(temporary_path, credentials_dir / f"{profile}.json")

Lier à nouveau un client

Liez à nouveau un client dans les cas suivants :

  • Une actualisation a renvoyé invalid_grant.
  • Vous avez perdu un jeton d’actualisation, ou l’un d’eux a fuité.
  • Vous avez perdu la réponse de l’étape 8 pour billing:attribution offline_access, ou l’étape 8 a renvoyé invalid_grant pour une telle connexion.
  • Un jeton d’actualisation est proche de son expiration.

Suivez ces étapes :

  1. Sur votre page User profiles, vérifiez si le client s’affiche comme Linked. Après invalid_grant, demandez d’abord à votre équipe de compte Anthropic si l’organisation du client est suspendue : une fois la suspension levée, le jeton d’actualisation que vous détenez fonctionne à nouveau. Si toutes les connexions renvoient invalid_grant en même temps, cherchez une cause de votre côté, par exemple un espace de travail archivé, avant de dissocier qui que ce soit.
  2. Si le client s’affiche comme Linked, dissociez-le, comme le décrit Dissocier un client. La dissociation révoque les jetons de la connexion. Effectuez-la lorsqu’un administrateur de l’organisation du client est prêt à approuver, car la facturation via la connexion s’arrête jusqu’à ce qu’il le fasse.
  3. Effectuez à nouveau les étapes 5 à 8 avec le profil utilisateur existant du client. Stockez le nouvel ID de connexion et les nouveaux jetons à la place des précédents.

Désactiver l’authentification opérateur seul

Pour empêcher les requêtes qui s’authentifient uniquement en tant que votre compte de service opérateur de facturer des clients, activez Disable operator-only tokenless authentication (le paramètre disable_operator_only_auth de l’application). Il se trouve dans l’onglet Client authentication de l’application, sous le compte de service opérateur. Votre application doit disposer des portées billing:attribution et offline_access ainsi que d’un espace de travail pour ses jetons OAuth. Avant de l’activer, assurez-vous que chaque client lié a approuvé billing:attribution offline_access et que vos requêtes avec leurs jetons d’accès fonctionnent. Tant qu’il est activé, seul le jeton d’accès d’une connexion billing:attribution peut facturer le client de cette connexion. Une requête qui s’authentifie uniquement en tant que compte de service et qui définit bill_to: "user_profile" est refusée avec 403 user_profile_not_billable. Le client s’affiche toujours comme Linked ; surveillez donc cette erreur dans vos journaux. Le compte de service peut toujours gérer les profils utilisateur et envoyer les requêtes que vous payez. Vous pouvez désactiver à nouveau ce paramètre.

Initialisation des extraits de code des jetons OAuth

Les exemples de cette section partagent la configuration suivante. Elle définit :

  • les imports, qui incluent le paquet httpx
  • l’ID client de votre application et le type d’assertion client
  • ConnectionTokens, qui contient les jetons d’une connexion, leurs dates d’expiration et sa marque on_hold
  • RefreshOnHold, l’erreur que refresh_connection() lève lorsqu’un jeton d’actualisation ne doit pas être envoyé à nouveau : il a peut-être déjà été utilisé, ou le point de terminaison de jeton a répondu invalid_grant. refresh_connection() la lève également à chaque appel ultérieur, jusqu’à ce que vous retiriez on_hold dans les jetons stockés, par exemple une fois une suspension levée. Lorsqu’une actualisation a réussi et que seul votre coffre de secrets a refusé l’écriture, son new_tokens contient les jetons à stocker.
  • client_assertion(), qui lit le JWT de votre fournisseur d’identité depuis le fichier désigné par ANTHROPIC_IDENTITY_TOKEN_FILE. La revendication aud du JWT doit correspondre à l’audience indiquée dans les paramètres d’authentification client de votre application.
  • load_tokens() et save_tokens(), que vous écrivez pour votre propre coffre de secrets
import json
import os
import tempfile
import threading
import time
from collections import defaultdict
from dataclasses import dataclass, field, replace
from pathlib import Path

import httpx

AUTH = "https://auth.claude.com"
# à copier depuis platform.claude.com après avoir enregistré votre application OAuth.
CLIENT_ID = "YOUR_CLIENT_ID"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
REFRESH_MARGIN_SECONDS = 600
# Un rafraîchissement qui expire ici perd ses nouveaux jetons, prévoyez donc 10 secondes pour la
# réponse. Une connexion impossible à établir échoue en moins de 2.
REQUEST_TIMEOUT = httpx.Timeout(10, connect=2)
# Une seconde requête doit démarrer aussi vite après la première, ou pas du tout. La
# page indique 30 secondes, mais restez sous le délai de lecture de REQUEST_TIMEOUT : une
# requête qui a expiré ne doit pas être renvoyée.
SECOND_REQUEST_DEADLINE_SECONDS = 4


@dataclass
class ConnectionTokens:
    refresh_token: str = field(repr=False)
    access_token: str = field(repr=False)
    expires_at: int  # the access token's expiry time, in Unix seconds
    refresh_expires_at: int  # the refresh token's expiry time, in Unix seconds
    # True : le jeton d'actualisation a peut-être été utilisé. Ne le renvoyez pas.
    on_hold: bool = False


class RefreshOnHold(Exception):
    """The refresh token might have been used, so a person decides what to do next.

    Don't catch this to try again. If new_tokens is set, the refresh succeeded and
    only the write failed: store those tokens.
    """

    new_tokens: ConnectionTokens | None = None


def client_assertion() -> str:
    """Reads your identity provider's JWT on every call, because its file rotates."""
    return Path(os.environ["ANTHROPIC_IDENTITY_TOKEN_FILE"]).read_text().strip()


def load_tokens(connection_id: str) -> ConnectionTokens:
    """Reads the connection's newest tokens from your secret store."""
    raise NotImplementedError("Read the tokens from your secret store.")


def save_tokens(connection_id: str, tokens: ConnectionTokens) -> None:
    """Writes the connection's newest tokens to your secret store."""
    raise NotImplementedError("Write the tokens to your secret store.")

Gérer vos connexions

Afficher les clients dans la Console

En plus de la page des applications OAuth, vous pouvez afficher tous vos profils utilisateur sur la page User profiles de la Console. Sur cette liste et sur la page de détail de chaque profil utilisateur, Your spend correspond à votre propre coût pour les requêtes de ce profil utilisateur. Il s’agit du coût avant qu’Anthropic n’applique d’éventuels crédits. Ces pages désignent une connexion par le terme « link » (lien) : un profil utilisateur disposant d’une connexion active affiche Linked, et un profil dont la connexion a pris fin affiche Unlinked.

Cliquez sur un profil utilisateur pour afficher une vue plus détaillée de son utilisation au cours des 7, 28 ou 90 derniers jours.

Suivre l’utilisation de chaque client

La Claude Console et l’API Usage and Cost Analytics indiquent toutes deux l’utilisation de chaque profil utilisateur. Toutes deux comptabilisent les requêtes que vous payez et celles que votre client paie. Aucune n’indique ce que le client a payé ni les tarifs du client.

Dans la Console, la page User profiles répertorie Requests, Tokens et Your spend pour chaque profil utilisateur sur les 28 derniers jours. Une requête que votre client paie s’ajoute aux Requests et aux Tokens du profil et n’ajoute rien à Your spend.

Appelez l’API avec un identifiant de l’Admin API, comme un jeton d’accès OAuth disposant de la portée org:admin ou une clé Admin API. N’utilisez pas votre compte de service opérateur (étape 3). Sa règle de fédération accorde workspace:developer par défaut, et non org:admin. La portée org:admin couvre l’ensemble de l’Admin API ; ne l’ajoutez donc pas au compte de service opérateur.

Pour obtenir un rapport par profil utilisateur via l’API, appelez son point de terminaison d’utilisation ou son point de terminaison de coûts. Pour obtenir une ligne par profil utilisateur, regroupez uniquement par user_profile_id et omettez time_bucket_width. Seul un profil utilisateur ayant une utilisation dans la période que vous demandez obtient une ligne. Une ligne supplémentaire a un user_profile_id nul. Elle contient l’utilisation qui ne désignait aucun profil et l’utilisation mesurée en dehors des requêtes, comme le temps de conteneur d’exécution de code.

Sur le point de terminaison de coûts, une requête que votre client paie ajoute 0 à amount et son prix catalogue à list_amount. Le champ amount correspond à la même mesure que Your spend. L’API ne dispose d’aucun champ, filtre ni valeur group_by[] indiquant qui a payé. Une ligne avec un amount de 0 et un list_amount supérieur à 0 signifie généralement que le client a payé chaque requête de cette ligne.

N’utilisez pas ces chiffres pour arrêter l’utilisation d’un client à un montant que vous choisissez. Ni la Console ni l’API ne fournissent de rapports en temps réel. Les chiffres de la Console sont actualisés environ une fois par heure, et une requête peut mettre quelques heures à apparaître. Pour le délai de l’API, consultez Fraîcheur des données. Plafonds de dépenses indique ce que font les propres limites du client.

Dissocier un client

Pour dissocier un client dans la Console, utilisez la liste de la page User profiles ou le bouton Unlink en haut à droite de la page de détail d’un profil utilisateur.

Pour dissocier un client depuis votre back-end, envoyez l’ID de connexion que vous avez stocké à l’étape 8 au point de terminaison de révocation, avec la même authentification client que pour l’échange du code. Pour désigner plutôt la connexion par son profil utilisateur, envoyez user_profile_id à la place de connection_id.

def revoke_connection(connection_id: str) -> list[str]:
    response = httpx.post(
        f"{AUTH}/v1/oauth/revoke",
        json={
            "connection_id": connection_id,
            "client_id": CLIENT_ID,
            "client_assertion_type": JWT_BEARER,
            "client_assertion": client_assertion(),
        },
    )
    response.raise_for_status()
    # ID des connexions terminées par cette requête. La liste est vide si la
    # connexion était déjà terminée ou si l'ID est inconnu.
    return response.json()["revoked_connection_ids"]

auth.claude.com répond avec un HTTP 200 et revoked_connection_ids, les ID des connexions auxquelles cette requête a mis fin. La liste est vide si la connexion a déjà pris fin ; vous pouvez donc répéter sans risque une requête qui envoie connection_id. Elle est également vide si l’ID est inconnu ; une liste vide ne prouve donc pas que la connexion existait. Consultez Révocation pour les autres paramètres et Erreurs du point de terminaison de révocation.

Une fois la connexion terminée, le profil utilisateur s’affiche comme Unlinked, et une requête qui définit bill_to: "user_profile" pour ce client reçoit user_profile_not_billable. Vous pouvez toujours servir le client à vos propres frais avec bill_to: "self". Après la liaison décrit ce que voit votre client, et E-mails concernant la liaison et la dissociation indique quelle méthode de dissociation lui envoie un e-mail.

Lier un client à une autre organisation Claude

Pour lier le profil utilisateur d’un client à une autre organisation Claude, dissociez le client, puis liez-le à nouveau.

Après la dissociation, les requêtes que vous facturez à ce client sont refusées. Cela dure jusqu’à ce qu’un utilisateur approuve pour l’autre organisation et que vous échangiez le code à l’étape 8. Suivez ces étapes lorsque cet utilisateur est prêt à approuver :

  1. Ignorez cette étape si votre client a déjà dissocié votre application sur sa page Linked platforms. Sinon, dissociez le client, comme le décrit Dissocier un client. Le profil utilisateur s’affiche alors comme Unlinked sur votre page User profiles.
  2. Effectuez à nouveau les étapes 5 à 8 avec le même profil utilisateur. Pour l’étape 7, l’utilisateur a besoin d’un compte disposant du rôle Admin ou Facturation dans l’autre organisation. Demandez à l’utilisateur d’approuver pour cette organisation.
  3. Stockez le nouvel ID de connexion à la place du précédent. Si vous utilisez les jetons de la connexion, faites de même avec les nouveaux jetons.

Tant que le client n’est pas dissocié, la page d’approbation ne permet à un utilisateur d’approuver que pour l’organisation déjà liée.

Un plafond de dépenses appartient à une organisation cliente et à votre application ; le plafond de la première organisation n’est donc pas reporté. Plafonds de dépenses en indique les règles.

Erreurs attendues

Lorsqu’une requête définit bill_to: "user_profile", Anthropic facture votre client ou refuse la requête. Anthropic ne vous facture jamais silencieusement à la place. Sur /v1/messages, le code de la liste suivante se trouve dans error.details.error_code. Sur /v1/chat/completions, vous obtenez le même statut HTTP et le même message au format OpenAI, sans le code :

  • 403 permission_error, user_profile_not_billable : Anthropic ne peut pas facturer ce client pour cette requête, et la réponse n’en indique pas la raison. Non réessayable, sauf dans les 10 premières secondes suivant une nouvelle connexion. Avant de demander au client d’effectuer à nouveau la liaison, consultez Causes de user_profile_not_billable : une nouvelle liaison ne résout que certaines d’entre elles. Vous pouvez toujours servir le client à vos propres frais en renvoyant la requête avec bill_to: "self". Dans le SDK Anthropic, gérez user_profile_not_billable au moyen de la classe d’erreur correspondant au statut 403, à savoir PermissionDeniedError. Celle-ci correspond également à d’autres erreurs 403 ; vérifiez donc aussi le code d’erreur.
  • 402 billing_error, linked_organization_billing_unavailable : Anthropic ne peut actuellement pas facturer l’organisation du client (par exemple, elle est suspendue, ou son crédit s’épuise après que Claude a commencé une réponse). La réponse n’en indique pas la raison. Un client qui n’a aucun crédit au moment où la requête arrive reçoit linked_organization_spend_limit_reached à la place. Non réessayable. Demandez au client de vérifier son compte Claude Platform. Vous pouvez toujours le servir à vos propres frais en renvoyant la requête avec bill_to: "self".
  • 402 billing_error, linked_organization_spend_limit_reached : l’organisation du client a atteint une limite de dépenses qu’elle a définie. Il s’agit soit du plafond de dépenses qui s’applique à votre application, soit de la limite de dépenses mensuelle de l’ensemble de l’organisation. L’API Claude envoie le même code lorsque l’organisation n’a aucun crédit pouvant payer la requête. La réponse n’indique pas laquelle. La requête a été refusée avant que Claude ne commence une réponse. Non réessayable. Vous pouvez toujours servir le client à vos propres frais en renvoyant la requête avec bill_to: "self". Demandez au client de vérifier les points suivants dans la Claude Console :
    • Le plafond de dépenses de votre application : sur la page de votre application sous Linked platforms, il peut définir ou augmenter le plafond de dépenses. Un plafond défini à cet endroit remplace tout plafond par défaut qu’il a défini pour toutes les plateformes liées.
    • La Limite de dépenses mensuelles de l’organisation : sous Limites de dépenses, il peut l’augmenter.
    • Le solde de crédit : sur sa page Facturation, il peut consulter son solde de crédit et acheter du crédit. Certains crédits ne peuvent pas payer ces requêtes : consultez Quels crédits peuvent payer.
  • 503 overloaded_error : Anthropic n’a pas pu confirmer pour le moment si le client peut être facturé. Réessayez avec un délai progressif et respectez l’en-tête retry-after. La requête n’a été ni servie ni facturée.
  • 400 invalid_request_error, user_profile_required : vous avez défini bill_to: "user_profile" sans l’en-tête anthropic-user-profile-id. Une telle requête nécessite l’en-tête, sauf si elle utilise le jeton d’accès d’une connexion et que l’en-tête est facultatif. Pour savoir si l’en-tête est facultatif, consultez la note dans Appeler Claude avec le jeton d’accès d’une connexion.
  • 400 invalid_request_error, sans code d’erreur : l’en-tête anthropic-user-profile-id contient un ID mal formé ou qui n’est pas un profil utilisateur de votre organisation.
  • 400 invalid_request_error, sans code d’erreur : la requête s’est authentifiée avec le jeton d’accès d’une connexion, et a soit défini bill_to: "self", soit désigné un profil utilisateur autre que celui auquel le jeton est limité. Consultez Appeler Claude avec le jeton d’accès d’une connexion.

Sur /v1/messages et /v1/chat/completions, le jeton d’accès d’une connexion ne peut pas envoyer une requête que vous payez. Pour renvoyer une requête refusée avec bill_to: "self", authentifiez-vous depuis votre propre back-end avec l’identifiant propre de votre compte de service opérateur. Appeler Claude avec le jeton d’accès d’une connexion répertorie les refus propres au jeton lui-même.

Une réponse réussie n’indique pas qui a été facturé ; conservez donc votre propre registre des requêtes que vous avez envoyées avec bill_to: "user_profile".

Causes de user_profile_not_billable

Vérifiez les points suivants dans l’ordre :

  • Votre requête. La requête doit s’authentifier en tant que compte de service opérateur de votre application OAuth (étape 3). Le jeton d’accès d’une connexion s’authentifie également en tant que ce compte de service. Une requête qui s’authentifie de toute autre manière est refusée. Par exemple, un autre compte de service, ou une clé API qui n’est pas liée à ce compte de service. Si l’en-tête anthropic-user-profile-id désigne l’un de vos profils qui n’est pas lié, la requête est refusée. Si l’identifiant ou l’en-tête est incorrect, corrigez la requête. Une nouvelle connexion n’y change rien.
  • La connexion. Le client n’a pas effectué la liaison via cette application, ou la connexion a pris fin : un administrateur de son organisation ou de la vôtre y a mis fin, ou votre back-end l’a fait. Une connexion qui a pris fin s’affiche comme Unlinked sur votre page User profiles. Un profil lié uniquement via votre application de test n’est pas lié à votre application de production. Cessez de facturer ce client jusqu’à ce qu’il effectue la liaison. Le jeton d’accès d’une connexion est limité à cette connexion ; après que le client a effectué à nouveau la liaison, utilisez donc le jeton d’accès de la nouvelle connexion. Si votre application a désactivé l’authentification opérateur seul, vous ne pouvez facturer un client qu’avec le jeton d’accès de sa connexion. Dans ce cas, un client pour lequel vous ne détenez aucun jeton valide d’une connexion billing:attribution s’affiche comme Linked, mais doit approuver à nouveau, comme le décrit Lier à nouveau un client.
  • L’organisation du client. Il doit s’agir d’un client éligible. Vous ne pouvez pas le vérifier de votre côté ; demandez donc à votre équipe de compte Anthropic.

Une nouvelle connexion fonctionne généralement immédiatement, mais cela peut prendre environ 10 secondes après l’échange de l’étape 8. Si une requête est refusée avec user_profile_not_billable pendant ces 10 secondes, envoyez-la à nouveau. Passé ce délai, attendre ou réessayer ne change pas le résultat. Journalisez l’intégralité de error.message et l’en-tête de réponse request-id de chaque requête refusée. Si un client dont la connexion s’affiche comme Linked est toujours refusé et que votre requête est correcte, envoyez le request-id d’une requête refusée à votre équipe de compte Anthropic, afin qu’Anthropic puisse rechercher la raison du refus.

Le point de vue de votre client

Liaison

Votre utilisateur approuve sur auth.claude.com après que votre application l’y a redirigé à l’étape 6. L’étape 7 répertorie les écrans de la page d’approbation. Chaque écran affiche le nom de votre application et comporte un bouton Cancel. Voici ce que fait l’utilisateur sur chaque écran :

  • Select an organization : l’utilisateur choisit laquelle de ses organisations Claude lier. La page n’affiche cet écran que si l’utilisateur a le choix entre plusieurs organisations.
  • How billing works : l’utilisateur lit l’écran et clique sur Continue.
  • Set a monthly spend limit : l’utilisateur saisit une limite pour votre application en dollars américains entiers et clique sur Continue. Le champ du montant est vide au départ ; la page ne choisit donc pas de limite à la place de l’utilisateur. Continue without a limit n’enregistre aucune nouvelle limite, et un plafond ou une valeur par défaut que le client a enregistré auparavant continue de s’appliquer. La limite que saisit l’utilisateur est le plafond de dépenses que décrit Plafonds de dépenses. Cet écran diffère tant que votre application est en phase de test : consultez Tant que votre application est en phase de test.
  • Le dernier écran : cet écran répertorie ce que votre application pourra faire, y compris la limite choisie par l’utilisateur. L’utilisateur clique sur Link and authorize.

La page d’approbation utilise le compte Claude connecté dans le navigateur, quel qu’il soit, et ne propose que les organisations Claude de ce compte. Il peut ne pas s’agir du compte auquel votre utilisateur s’attend, par exemple un compte personnel au lieu d’un compte professionnel. Votre application ne peut pas choisir le compte. Les paramètres OpenID Connect prompt=select_account et login_hint ne modifient pas le compte utilisé par la page.

Après la liaison

Vos clients gèrent leurs connexions sur la page Linked platforms de la Claude Console. Ils peuvent dissocier votre application à tout moment. Anthropic ne vous avertit pas lorsqu’ils le font : vous ne recevez ni événement webhook ni e-mail.

Après qu’un client a effectué la dissociation, les requêtes que vous facturez à ce client sont refusées avec 403 user_profile_not_billable (consultez Causes de user_profile_not_billable). Le profil utilisateur du client s’affiche comme Unlinked sur votre page User profiles dans la Console. Pour effectuer à nouveau la liaison, effectuez à nouveau les étapes 5 à 8 avec le profil utilisateur existant du client.

E-mails concernant la liaison et la dissociation

Les e-mails d’Anthropic concernant la liaison et la dissociation sont envoyés aux membres de l’organisation de votre client qui disposent du rôle Admin ou Facturation. Chaque e-mail renvoie vers la page Linked platforms du client. L’envoi d’un e-mail par Anthropic dépend de l’événement :

  • Lorsque le client lie votre application : Anthropic envoie un e-mail lorsque vous échangez le code à l’étape 8. Aucun e-mail n’est envoyé pour une approbation dont vous n’échangez jamais le code. Aucun e-mail n’est non plus envoyé lorsqu’un utilisateur approuve à nouveau alors que le client est toujours lié.
  • Lorsque le client dissocie votre application : Anthropic envoie un e-mail. Celui-ci ne nomme pas la personne qui a dissocié votre application.
  • Lorsque vous dissociez le client depuis votre back-end : Anthropic envoie un e-mail.
  • Lorsque vous dissociez le client dans la Console : Anthropic n’envoie aucun e-mail.

Anthropic ne garantit pas qu’un e-mail soit envoyé ou remis. Prévenez vous-même votre client lorsque vous le dissociez. Ne comptez pas sur ces e-mails pour informer un client qu’il est lié.

Plafonds de dépenses

Votre client peut définir un plafond de dépenses mensuel pour votre application, en dollars américains (USD). La page d’approbation appelle ce plafond une limite de dépenses mensuelle, et l’utilisateur qui effectue la liaison peut le définir à cet endroit (consultez Liaison). Il est distinct de la Limite de dépenses mensuelles de l’organisation, qui s’applique à l’ensemble de l’organisation. Vous ne pouvez pas consulter le plafond d’un client, ni la part de celui-ci qu’il a utilisée.

Lorsque les dépenses du client via votre application atteignent le plafond, l’API Claude refuse les requêtes que vous lui facturez avec une erreur 402. Consultez Erreurs attendues. Les refus durent jusqu’à 00:00 UTC le premier jour du mois suivant, ou jusqu’à ce que le client augmente ou supprime le plafond. Une modification du plafond peut mettre environ une minute à s’appliquer.

Après la liaison, un membre de l’organisation du client disposant du rôle Admin ou Facturation gère les plafonds sur la page Linked platforms de la Console :

  • Définir ou modifier un plafond : il clique sur votre application, puis sur Set spend cap ou Edit spend cap.
  • Définir une valeur par défaut : sous Default spend cap, il clique sur Set default ou Edit. Chaque application liée qui n’a pas son propre plafond peut dépenser jusqu’à la valeur par défaut chaque mois. Les applications ne la partagent pas.
  • Supprimer un plafond : il clique sur votre application, sur Edit spend cap, puis sur Remove cap. Votre application utilise alors la valeur par défaut. S’il n’existe pas de valeur par défaut, votre application n’a aucun plafond.

Le plus petit plafond est de 0 $ USD, ce qui refuse chaque requête que vous facturez à ce client. La Console accepte des montants en dollars entiers, sans maximum pratique. Le plafond comptabilise les coûts des tokens et les frais de recherche web aux prix catalogue, avant toute remise négociée. La facture du client peut différer du montant que comptabilise le plafond.

Un plafond peut être supérieur à la Limite de dépenses mensuelles de l’organisation, que le client définit sous Limites de dépenses. L’API Claude refuse les requêtes que vous facturez au client lorsque l’une ou l’autre est atteinte.

Tant que votre application est en phase de test

Ces limites s’appliquent chaque fois qu’une personne lie votre application ou modifie son plafond alors que l’application est en phase de test, en cours d’examen ou non approuvée :

En phase de test, en cours d’examen ou non approuvéeUne fois l’application en production
Une limite de dépenses mensuelle sur la page d’approbationObligatoire, 50 $ USD ou moinsFacultative
Le champ du montant sur la page d’approbationCommence à 50 $ USDVide au départ
Continue without a limit sur la page d’approbationNon proposéProposé
La suppression du plafond dans la ConsoleImpossiblePossible
Le plafond le plus élevé qu’un client peut définir50 $ USDAucun maximum pratique

Une fois votre application en production, un plafond qu’un client a enregistré auparavant reste en place. Le client peut alors l’augmenter ou le supprimer.

Accompagner vos clients

Vous assurez le support de vos clients pour tout ce qui concerne votre application, y compris l’utilisation de Claude que vous leur facturez. Anthropic fournit à vos clients la page d’approbation et la page Linked platforms dans la Claude Console. Sur la page Linked platforms, un membre disposant du rôle Admin ou Facturation peut voir ce que votre application a coûté à l’organisation ce mois-ci. Il peut également définir un plafond de dépenses mensuel pour votre application, et la dissocier. Toutes les autres questions concernant votre application doivent vous être adressées ; indiquez donc à vos clients comment vous joindre.

Initialisation des extraits de code

Les exemples Python de cette page partagent la configuration suivante, que vous écrivez une seule fois. Elle définit :

  • les imports
  • l’ID client et l’URI de redirection de votre application
  • la valeur de l’en-tête bêta de facturation
  • un client de l’API Claude qui s’authentifie en tant que votre compte de service
  • client_assertion, qui renvoie l’assertion client que votre back-end envoie à auth.claude.com
# Les exemples Python supposent l'initialisation et les variables suivantes
import secrets
from urllib.parse import urlencode

import anthropic
import httpx
from anthropic.lib.credentials import IdentityTokenFile
from anthropic.types import Message
from anthropic.types.beta import BetaMessage
from authlib.oauth2.rfc7636 import create_s256_code_challenge

AUTH = "https://auth.claude.com"
# à copier depuis platform.claude.com après l'enregistrement de votre app OAuth.
CLIENT_ID = "YOUR_CLIENT_ID"
REDIRECT_URI = "https://app.example.com/claude/billing/callback"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
BILLING_BETA = "user-profiles-billing-2026-10-01"

# Client API. Le SDK échange le JWT d'identité de votre charge de travail contre un jeton
# d'accès et le renouvelle, vous ne gérez donc jamais "Bearer <access token>" vous-même.
client = anthropic.Anthropic()

# Assertion client pour auth.claude.com : le JWT d'identité lui-même, relu à
# chaque appel car le fichier change. Si les paramètres d'authentification client de
# votre app indiquent une audience différente de votre règle de fédération, pointez vers
# un second fichier de jeton : IdentityTokenFile("/path/to/other/token").
client_assertion = IdentityTokenFile()

Cette page vous a-t-elle été utile ?