Claude Platform Docs
AmministrazioneClaude Platform OAuth

Linked billing

Consenti ai tuoi clienti di collegare la propria organizzazione Claude Platform alla tua app con OAuth e addebita l’utilizzo di Claude all’organizzazione del cliente.

Linked billing consente ai tuoi clienti di pagare l’utilizzo di Claude nella tua app tramite la propria organizzazione Claude. Un cliente collega la propria organizzazione Claude alla tua app una sola volta. L’API chiama questo collegamento “connection” (connessione). Dopo che il cliente si è collegato, scegli su ogni richiesta alla Claude API se paga il cliente o se paghi tu. Il cliente può scollegare la tua app in qualsiasi momento. Se una richiesta che contrassegni per il cliente non può essergli addebitata, la Claude API la rifiuta invece di addebitarla a te.

Questa guida è per gli sviluppatori i cui utenti dell’app sono principalmente clienti di Claude Platform. Aggiungi un pulsante “Link your Claude organization” alla tua app. Il tuo utente fa clic sul pulsante, accede a Claude e approva la tua app affinché addebiti alla sua organizzazione Claude le richieste alla Claude API che il cliente ti chiede di effettuare. La tua app aggiunge quindi un campo billing_policy alle richieste pagate dal cliente.

Clienti ed endpoint idonei

Clienti idonei: l’addebito in questo modo è possibile solo se l’organizzazione Claude Platform del cliente paga Anthropic direttamente per il proprio utilizzo dell’API. Sono validi sia i crediti prepagati sia il pagamento su fattura. Le organizzazioni fatturate tramite un marketplace cloud (AWS, Google Cloud o Azure) non possono ricevere addebiti tramite questa integrazione. Lo stesso vale per le organizzazioni che hanno solo un piano di abbonamento Claude. Le richieste per esse vengono rifiutate con 403 user_profile_not_billable.

Le richieste vengono eseguite nella tua organizzazione, quindi si applicano i tuoi “rate limit” (limiti di velocità), l’accesso ai modelli, il livello di servizio, la conservazione dei dati e le chiavi di crittografia. Gli accordi sui dati propri del tuo cliente non si applicano a queste richieste, inclusi la “zero data retention” (conservazione zero dei dati), o ZDR, un “business associate agreement” (accordo con un business associate), o BAA, e le “customer-managed encryption keys” (chiavi di crittografia gestite dal cliente), o CMEK. Non collegare clienti che necessitano di copertura HIPAA, FERPA o CMEK per questo utilizzo.

Endpoint supportati: billing_policy è supportato su:

  • /v1/messages
    • Limitazione nota: una richiesta che addebita il tuo cliente (bill_to: "user_profile") non può utilizzare le funzionalità di esecuzione del codice a pagamento (l’API restituisce un 400), quindi invia tali richieste con bill_to: "self" o senza billing_policy.
  • /v1/chat/completions
  • /v1/messages/count_tokens accetta il campo billing_policy e lo ignora, così puoi contare i token sul corpo esatto che stai per inviare.

Message Batches (/v1/messages/batches) non supporta ancora la fatturazione al tuo cliente. Invia le richieste in un batch con bill_to: "self" o senza billing_policy, e ti verranno fatturate come di consueto. Una richiesta in un batch che imposta bill_to: "user_profile" viene rifiutata: il suo risultato è errored con un invalid_request_error, né a te né al tuo cliente viene fatturata, e le altre richieste del batch vengono eseguite come di consueto.

Per richiedere il supporto su un altro endpoint, contatta il tuo team di riferimento Anthropic.

Quali crediti possono pagare

Non tutto il credito può pagare una richiesta che una piattaforma addebita a un cliente. Ciò che può pagare dipende dall’organizzazione a cui viene addebitata: il cliente, se addebiti a un cliente, oppure la tua organizzazione, se una piattaforma addebita a te.

Il credito acquistato nella Claude Console per quell’organizzazione può pagare queste richieste. Se quell’organizzazione ha il pagamento su fattura, queste richieste le vengono fatturate.

Alcuni crediti promozionali di Anthropic non possono pagare queste richieste. Tra questi rientrano i crediti API mensili inclusi nei piani Claude Max, Ultra e Team. I crediti dei programmi per partner, VC e startup di Anthropic non sono idonei a pagare queste richieste.

Quando nulla sull’account di quell’organizzazione può pagare una richiesta, la Claude API può rifiutarla con un 402. La risposta non indica se il rifiuto sia stato causato da una mancanza di credito o da un limite di spesa. Consulta Errori previsti.

Processo di configurazione

Esegui questi tre passaggi una sola volta. Registrano la tua app presso Anthropic. Successivamente, Quale profilo utente collegare spiega una regola che ti serve prima di creare i profili utente.

Passaggio 1: Crea l’app

Crea l’app OAuth nella Claude Console. È la registrazione che identifica il tuo prodotto presso Anthropic: associa il tuo “redirect URI” (URI di reindirizzamento) a un “client ID” (ID client), e il suo nome è ciò che il tuo utente vede nella pagina di approvazione.

Un membro della tua organizzazione con il ruolo Admin apre la pagina delle app OAuth nella Console e clicca su Crea. Inserisci il nome della tua app e il redirect URI (l’indirizzo nella tua app a cui il browser ritorna dopo l’approvazione). In What the app can do, seleziona Bill and link to organizations.

Si apre la pagina della nuova app. Copia il client ID che la Console mostra per l’app. La tua app lo invia nel Passaggio 5 quando richiede una pagina di approvazione, nel Passaggio 6 quando reindirizza il browser e nel Passaggio 8 quando scambia il codice, in modo che Anthropic sappia quale app sta effettuando la richiesta. Il client ID è pubblico. Nella scheda Aspetto, imposta il nome, la homepage e l’URL del logo della tua app.

Nella scheda Impostazioni, Who can link riporta Test users only per una nuova app, che parte in fase di test. Dopo che hai pubblicato la tua app ed è attiva, l’impostazione riporta Any Claude user.

Passaggio 2: Configura l’autenticazione del client

Configura il modo in cui il tuo back end dimostra a auth.claude.com che le sue richieste provengono dalla tua app. Questo sostituisce un client secret: Anthropic non emette client secret per le app OAuth.

Nella scheda Client authentication dell’app, seleziona il tuo Provider di identità (l’emittente che firma i token del tuo back end). Per aggiungerne uno, clicca su Register a new issuer. Quindi imposta un Pattern del soggetto, oppure delle condizioni sui claim in Opzioni di corrispondenza avanzate, a cui quei token devono corrispondere. Dopo il salvataggio, la scheda mostra l’audience prevista. Il claim aud della tua asserzione client deve essere esattamente quel valore.

Passaggio 3: Configura l’identità del tuo back end

Il tuo back end ha bisogno di una propria identità per chiamare la Claude API. Crea due elementi:

  • Un “service account” (account di servizio). Si tratta di un account non umano nella tua organizzazione Claude. Il tuo back end si autentica come questo account quando chiama la Claude API.
  • Una seconda regola di federazione. Come la regola per l’autenticazione del client dell’app nel Passaggio 2, consente al tuo back end di autenticarsi con i token del tuo provider di identità.

Per configurarli nella Claude Console, segui la guida Workload Identity Federation.

Quindi, nella scheda Client authentication dell’app, seleziona quell’account di servizio come account di servizio operatore dell’app. Solo quell’account di servizio è autorizzato a inviare richieste di inferenza e ad attribuire la fatturazione ai profili utente collegati. Un account di servizio può essere l’operatore di una sola app OAuth.

Per impostazione predefinita, qualsiasi richiesta autenticata come quell’account di servizio può addebitare ogni cliente collegato, impostando l’header del profilo utente e bill_to nella Messages API. Per ottenere token di autenticazione vincolati soltanto a una connessione specifica, consulta Token OAuth per ciascuna connessione. Prima di collegare i clienti, imposta un workspace per la tua app. Il Passaggio 8 restituisce un token di questo tipo per ogni cliente, e richiede che l’app specifichi un workspace predefinito nella tua organizzazione in cui viene eseguita l’inferenza. Se vuoi dei “refresh token” (token di aggiornamento) per ciascuna connessione, attiva anche Offline access per la tua app. Quindi richiedi offline_access nel flusso di autorizzazione, nel Passaggio 5, prima di collegare i clienti.

Un “user profile” (profilo utente) è un record nella tua organizzazione Claude che rappresenta uno dei tuoi clienti. Ogni richiesta che addebita il cliente include l’ID del profilo, in modo che Anthropic sappia a quale cliente addebitarla. Per tutto il resto di ciò che fanno i profili, consulta Profili utente per l’attribuzione ai clienti finali.

Stabilisci quale profilo utente rappresenta ciascun cliente prima di collegare il tuo primo cliente. All’interno di un’app, le connessioni sono uno a uno:

  • L’organizzazione Claude di un cliente può essere collegata a uno solo dei tuoi profili utente.
  • Un profilo utente può essere collegato a una sola organizzazione Claude.

L’organizzazione Claude del cliente è quella che l’utente seleziona quando approva la tua app. Per sapere come i team di un cliente usano le organizzazioni Claude, chiedilo al cliente. Per applicare la regola uno a uno ai record dei tuoi clienti:

  • Diversi team di un cliente condividono un’organizzazione Claude: usa un solo profilo utente per tutti i team.
  • Ogni team ha la propria organizzazione Claude: crea un profilo utente per ciascuna organizzazione.

Qualsiasi profilo utente attivo nella tua organizzazione può essere collegato, purché la regola uno a uno sia rispettata. Il collegamento non modifica il profilo, il suo ID né la sua cronologia di utilizzo. Se colleghi un secondo profilo utente a un’organizzazione Claude già collegata, l’approvazione viene rifiutata: consulta user_profile_already_linked.

Un profilo utente per ogni persona

Potresti avere già un profilo utente per ogni persona che usa il tuo prodotto. Diverse di queste persone potrebbero lavorare per lo stesso cliente. In tal caso, Anthropic consiglia di creare un ulteriore profilo utente per l’organizzazione Claude del cliente e di collegare quel profilo.

L’ID del profilo da inviare dipende da chi paga la richiesta:

  • Richieste che addebiti al cliente: invia l’ID del profilo del cliente. Per identificare anche la persona in una richiesta a /v1/messages, imposta metadata.user_idAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) su un identificatore di quella persona. L’identificatore è facoltativo e aiuta Anthropic a rilevare un uso improprio da parte di una singola persona. Usa un valore opaco, non un nome, un indirizzo email o un numero di telefono.
  • Richieste che paghi tu: puoi continuare a inviare l’ID del profilo proprio della persona.

Collega ciascun cliente

Esegui i Passaggi da 4 a 8 per ogni cliente che collega la propria organizzazione. I seguenti frammenti di codice Python richiedono l’SDK di Anthropic e alcune importazioni standard; consulta Inizializzazione dei frammenti di codice. Gli esempi negli altri linguaggi e la CLI prendono le credenziali dall’ambiente. Assicurati che ANTHROPIC_API_KEY non sia impostata, perché la tua app deve autenticarsi con Workload Identity Federation.

Aggiungi un pulsante “Link your Claude organization” nel punto del tuo prodotto in cui i tuoi clienti gestiscono la fatturazione o le integrazioni (per l’HTML, i colori e il logo del pulsante, consulta Esempi di branding). Comunica loro che, per collegarsi, devono avere il ruolo Amministratore o Fatturazione nella loro organizzazione Claude.

Per eseguire prima tu stesso i passaggi, consulta Esegui test come cliente.

Browser
Il tuo back end
auth.claude.com
Clicca su “Link your Claude organization”
5
Pushed authorization request con l'ID del profilo utente e una client assertion
request_uri
6
Reindirizza alla pagina di approvazione, cioè l'endpoint di autorizzazione
7
L'utente accede a Claude, sceglie l'organizzazione e approva
Reindirizza al tuo URI di reindirizzamento con un codice monouso e lo state
Consegna il codice e lo state
Verifica che lo state corrisponda
8
Richiesta di token con il codice, il code verifier PKCE e una client assertion
connection_id
Memorizza l'ID di connessione nel record del cliente

Passaggio 4: Crea un profilo utente per il cliente

Crea un profilo utente per l’organizzazione Claude di ciascun cliente e memorizzane l’ID nel record del cliente nel tuo prodotto.

Se hai già un profilo utente per l’organizzazione Claude di questo cliente, salta questo passaggio e usa l’ID di quel profilo. Per decidere di quale profilo si tratta, consulta Quale profilo utente collegare.

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")

Se la tua organizzazione rivende l’accesso all’API, invia anche "access_type": "passthrough" quando crei questo profilo. Questi esempi omettono access_type, il che crea un profilo application. Per i due tipi, consulta Decidi chi riceve un profilo.

La risposta contiene l’id del profilo, ad esempio uprof_01HV9Z.

Passaggio 5: Crea un URL di pushed authorization request

Crea una “pushed authorization request” (richiesta di autorizzazione inviata) che faccia riferimento al profilo utente del cliente ottenuto nel Passaggio 4. La risposta ti fornisce un request_uri. Nel passaggio successivo, lo usi per reindirizzare il tuo utente alla pagina di approvazione.

Prima di inviare la richiesta, il tuo back end crea due valori casuali e li memorizza associandoli alla sessione del browser e al record del cliente. Li usa entrambi di nuovo nel Passaggio 8:

  • Un valore state, che ti consente di verificare che il browser che ritorna alla tua app sia quello che ha avviato questa richiesta.
  • Un “code verifier” (verificatore del codice) PKCE, un segreto che solo il tuo back end conosce. La richiesta ne contiene un hash (il code challenge), e il Passaggio 8 invia il verificatore stesso, in modo che solo il tuo back end possa usare il codice che viene restituito.
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 risponde con HTTP 201, un request_uri e un expires_in di 600 secondi. Il request_uri identifica la pagina di approvazione per questa richiesta. Lo scope deve essere esattamente billing:attribution oppure billing:attribution offline_access. Per i dettagli, consulta Scope per una connessione di fatturazione. Gli esempi inviano billing:attribution. Se la tua app non ha questo scope, aggiungilo in Billing nella scheda Permissions dell’app.

connection_auth_target deve essere platform: le richieste di inferenza vengono eseguite nella tua organizzazione, autenticate come l’account di servizio operatore, ma possono addebitare il cliente.

user_profile_id deve essere l’ID di un profilo utente attivo nella tua organizzazione. Se la pushed authorization request non va a buon fine, auth.claude.com restituisce una risposta di errore OAuth al tuo back end. In tal caso, non reindirizzare il browser.

Passaggio 6: Invia il tuo utente alla pagina di approvazione di Claude

Per prima cosa, mostra al tuo utente quale account del tuo prodotto sta collegando e digli di verificare l’account Claude mostrato dalla pagina di approvazione. La pagina mostra con quale account Claude è stato effettuato l’accesso e consente all’utente di passare a un altro. La pagina di approvazione propone solo le organizzazioni dell’account Claude con cui è stato effettuato l’accesso nel browser, quindi l’account sbagliato può collegare l’organizzazione sbagliata. Paga l’organizzazione che l’utente collega.

Quindi, reindirizza il tuo utente all’endpoint di autorizzazione, che mostra una pagina di approvazione. Includi solo il tuo client_id e il request_uri del Passaggio 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

Passaggio 7: L’utente approva

La tua app non fa nulla in questo passaggio. L’utente esegue questi passaggi su auth.claude.com:

  1. L’utente accede a Claude, a meno che nel browser non sia già stato effettuato l’accesso.
  2. La pagina di approvazione mostra le seguenti schermate, ciascuna con il nome della tua app. Per sapere cosa fa l’utente in ciascuna schermata, consulta Collegamento.
    1. Select an organization, solo se l’utente può scegliere tra più organizzazioni.
    2. How billing works.
    3. Set a monthly spend limit.
    4. Un’ultima schermata con un pulsante Link and authorize.
  3. Quando l’utente fa clic su Link and authorize, auth.claude.com rimanda il browser alla tua app. La pagina di approvazione non mostra alcuna schermata di conferma.

Se l’utente annulla o non può approvare, non viene creata alcuna connessione: consulta Se il collegamento non si completa.

Passaggio 8: Gestisci il callback e salva la connessione

Dopo l’approvazione, auth.claude.com rimanda il browser al tuo redirect URI con un codice monouso e il tuo valore state. Questa richiesta al tuo redirect URI è chiamata callback. Il tuo back end scambia il codice con un ID di connessione e lo memorizza nel record del cliente. Questo completa la connessione. Il callback può contenere un parametro error e nessun codice. In tal caso non è stata creata alcuna connessione: consulta Se il collegamento non si completa.

Verifica che lo state corrisponda al valore memorizzato nel Passaggio 5, quindi scambia immediatamente il codice dal tuo back end, insieme al code verifier PKCE. Il codice è monouso e scade dopo 5 minuti.

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()
    # Per usare i token della connessione, salva tokens["access_token"], la sua scadenza
    # (da tokens["expires_in"]) e, con offline_access,
    # tokens["refresh_token"] come segreti qui: il codice non può essere riscambiato.
    # "ocon_..."; salvalo nel record del cliente
    return tokens["connection_id"]

La risposta contiene l’ID di connessione e il token di accesso della connessione, che può autenticare e addebitare il cliente che ha approvato. Se il cliente ha approvato offline_access, la risposta contiene anche un refresh token. Memorizza subito connection_id e i token: lo scambio restituisce i token una sola volta. Memorizza i token descrive la risposta.

Gli esempi in questa pagina che chiamano la Claude API si autenticano come l’account di servizio del Passaggio 3, non con un token di questa risposta. Chiama Claude con il token di accesso di una connessione spiega come usare il token al suo posto.

La risposta non identifica quale organizzazione Claude l’utente ha collegato.

Una connessione completata non garantisce che Anthropic possa addebitare il cliente. Ad esempio, l’organizzazione del cliente potrebbe non rientrare tra i clienti idonei. Consulta Aggiorna le chiamate a Claude ed Errori previsti per sapere come la Claude API verifica questo aspetto. A causa di tale verifica, formula il messaggio di successo come “collegato” anziché “fatturazione attiva”.

Se lo scambio viene rifiutato con unauthorized_client, consulta Lo scambio del codice restituisce unauthorized_client.

Esegui test come cliente

Per verificare che il collegamento funzioni, collega una tua organizzazione. Prima ti servono:

  • Una seconda organizzazione Claude di tua proprietà che faccia da cliente. Non puoi collegare la tua app all’organizzazione che la possiede. La pagina di approvazione non propone quell’organizzazione. La seconda organizzazione deve rientrare tra i clienti idonei.
  • Una persona con il ruolo Amministratore o Fatturazione in quell’organizzazione che approvi il collegamento.
  • Finché la tua app non è attiva, quella persona deve essere nell’elenco Test users della tua app. L’elenco si trova nella scheda Impostazioni dell’app, in Who can link. Aggiungi la persona tramite l’indirizzo email del suo account Claude e clicca su Save changes. Mentre la tua app è in fase di test indica il tetto di spesa che si applica. La rimozione di una persona dall’elenco termina i collegamenti che ha approvato.

Quindi, esegui i Passaggi da 4 a 8 e chiedi a quella persona di approvare nel Passaggio 7. Una volta creato il collegamento, il profilo utente riporta Linked nella tua pagina User profiles nella Console.

Se il collegamento non si completa

Quando l’utente non termina l’approvazione, o auth.claude.com la rifiuta, non viene creata alcuna connessione. Queste voci coprono gli esiti specifici di Linked billing. Per ogni altro errore, consulta Errori nel Riferimento OAuth.

Il tuo redirect URI riceve error=access_denied

La richiesta contiene anche il tuo valore state. Il tuo redirect URI riceve questo errore in casi come i seguenti:

  1. L’utente fa clic su Cancel in una qualsiasi schermata di approvazione.
  2. La pagina di approvazione non ha alcuna organizzazione da proporre all’utente, e l’utente fa clic sul pulsante che ritorna alla tua app. Ad esempio:
    • L’utente non ha il ruolo Amministratore o Fatturazione in alcuna organizzazione Claude Platform.
    • L’unica organizzazione dell’utente è quella che possiede la tua app. Consulta Esegui test come cliente.
    • Il profilo utente è già collegato a un’altra organizzazione Claude, e l’utente non ha il ruolo Amministratore o Fatturazione in quell’organizzazione.
    • Finché la tua app non è attiva, l’utente non è nel suo elenco Test users.

In ciascun caso di questo elenco, l’error_description riporta the user declined the request, quindi non puoi usarlo per distinguerli.

Un’ulteriore causa si trova nelle impostazioni della tua app. Se la tua app è attiva e Who can link mostra solo la tua organizzazione, nessuno al di fuori della tua organizzazione può collegare l’app. Seleziona Any Claude user e clicca su Save changes.

Comunica all’utente che il collegamento non si è completato e non dare per scontato che abbia rifiutato. Chiedigli di verificare con quale account Claude ha effettuato l’accesso e il suo ruolo nell’organizzazione che vuole collegare. Un request_uri non può essere usato di nuovo dopo che l’utente annulla o ritorna, quindi, per consentire all’utente di riprovare, ricomincia dal Passaggio 5.

La tua app riceve user_profile_already_linked

L’organizzazione Claude del cliente è già collegata alla tua app tramite un altro dei tuoi profili utente. auth.claude.com chiede all’utente di contattarti. Se l’utente ritorna alla tua app, il tuo redirect URI riceve error=user_profile_already_linked e il tuo valore state. Anche l’endpoint token può restituire questo errore quando scambi il codice nel Passaggio 8. Ciò accade, ad esempio, quando nel frattempo l’organizzazione è stata collegata tramite un altro profilo utente.

Anthropic non ti comunica quale organizzazione Claude collega un cliente, quindi non puoi saperlo in anticipo. La pushed authorization request nel Passaggio 5 va a buon fine, e auth.claude.com rifiuta la connessione solo quando l’utente approva.

L’errore non indica il profilo utente che detiene la connessione. Il detentore più probabile è un altro profilo collegato di questo cliente. Anthropic non mostra a quale organizzazione è collegato un profilo, quindi verifica con il cliente prima di agire. Se quel profilo detiene la connessione, esegui una delle seguenti operazioni:

  • Sulle richieste che addebiti a questo cliente, invia l’ID di quel profilo utente.
  • Termina quella connessione, come descritto in Scollegare un cliente, quindi esegui di nuovo i Passaggi da 5 a 8 con il profilo utente che è stato rifiutato.

Se nessuno dei profili di questo cliente è collegato, l’utente potrebbe aver selezionato un’organizzazione che appartiene a un altro dei tuoi clienti. Ricomincia dal Passaggio 5 e fai verificare all’utente quale organizzazione seleziona.

Il tuo redirect URI non riceve nulla

La tua app non può rilevare questi due casi:

  • L’utente chiude la pagina di approvazione.
  • Il request_uri è scaduto o è già stato usato. La pagina di approvazione mostra quindi un errore e non rimanda il browser alla tua app.

Se l’utente ritorna al tuo prodotto senza un callback, ricomincia dal Passaggio 5. Un request_uri non usato scade 10 minuti dopo la sua creazione.

Lo scambio del codice restituisce unauthorized_client

La tua app non è configurata per questa richiesta. Per un problema relativo al workspace, l’error_description indica la causa. Per un account di servizio operatore mancante, riporta solo the client is not registered for this grant. Il rifiuto non consuma il codice, quindi puoi scambiare di nuovo lo stesso codice finché non scade. Per prima cosa, verifica questi elementi nella Claude Console:

VerificaDoveCorrezione
L’app ha un account di servizio operatoreOperator service account nella scheda Client authentication dell’appSelezionane uno e clicca su Save. Il Passaggio 3 spiega come configurarne uno.
Il workspace dell’app non è mancante né archiviatoConfigura la tua appScegli un workspace. Finché l’app non ne ha uno, anche lo scambio viene rifiutato con unauthorized_client.

Un account di servizio salvato può impiegare un minuto o due per raggiungere auth.claude.com, quindi se lo scambio viene rifiutato di nuovo, attendi quel tempo e riprova. Se nel frattempo il codice è scaduto, fai approvare di nuovo l’utente (Passaggi da 5 a 8). Per le cause che error_description indica per i token di una connessione, consulta Memorizza i token e Aggiorna i token.

In qualsiasi altro caso, contatta il tuo team di riferimento Anthropic. Fai lo stesso se la Console indica che l’account di servizio non esiste più.

Pubblica la tua app

Finché la tua app non è attiva, solo le persone nel suo elenco Test users possono collegarla, quindi i tuoi clienti non possono farlo. Per pubblicare l’app, clicca su Publish app nella pagina dell’app nella Claude Console. Si apre una finestra di dialogo.

  • Se la tua organizzazione paga su fattura, l’app è attiva non appena confermi in quella finestra di dialogo.
  • Altrimenti, dimostri prima in quella finestra di dialogo di controllare il dominio dell’app, e Anthropic esamina quindi l’app.

La verifica del dominio: il dominio è quello della homepage della tua app. Ogni redirect URI deve trovarsi su quel dominio o su un suo sottodominio, tranne uno su localhost, 127.0.0.1 o [::1]. La verifica è un record DNS TXT. Le modifiche DNS possono richiedere fino a 48 ore, quindi inizia prima di aver bisogno che i clienti si colleghino. Se la tua organizzazione ha già verificato un dominio che copre la homepage e quei redirect URI, la finestra di dialogo salta la verifica. Un dominio verificato copre i suoi sottodomini.

Confermi nell’ultimo passaggio della finestra di dialogo. Se quel passaggio mostra una casella di controllo per accettare i Linked Billing Terms, selezionala. Quindi, clicca su Publish app nella finestra di dialogo.

La revisione: durante la revisione, lo stato dell’app nella Console riporta In review. L’app è attiva quando Anthropic la approva. Se Anthropic non la approva, lo stato riporta Not approved e non puoi pubblicare di nuovo l’app autonomamente. Per chiedere informazioni sulla decisione, contatta il supporto.

A meno che la tua organizzazione non paghi su fattura, una modifica al nome, al logo, alla homepage o ai redirect URI di un’app attiva rimanda l’app in revisione. I clienti già collegati restano collegati e mantengono il tetto che hanno salvato. Finché Anthropic non approva la modifica, solo le persone nell’elenco Test users possono collegare l’app.

Aggiorna le chiamate a Claude

Invia l’header anthropic-user-profile-id in ogni chiamata a /v1/messages e /v1/chat/completions per un cliente collegato. In una richiesta che addebiti al cliente, il valore dell’header è l’ID del profilo utente che detiene la connessione di quel cliente. Le chiamate che impostano billing_policy devono inviare anche l’header beta user-profiles-billing-2026-10-01.

Ogni richiesta per un cliente collegato viene addebitata al cliente oppure a te, e sei tu a scegliere su ogni richiesta. Gli esempi seguenti mostrano entrambi i casi.

Token OAuth per ciascuna connessione descrive un altro modo per autenticare le richieste di un cliente: un token di accesso che può addebitare solo quel cliente. Su /v1/messages e /v1/chat/completions, una richiesta con un token di questo tipo non può essere addebitata a te. Viene addebitata a quel cliente, anche senza billing_policy o l’header anthropic-user-profile-id, laddove questi siano facoltativi: consulta la nota in Chiama Claude con il token di accesso di una connessione. Se indica un altro profilo utente o imposta bill_to: "self", viene rifiutata. Non usarne mai uno per una richiesta che paghi tu.

Paga il tuo cliente

Aggiungi billing_policy con bill_to: "user_profile" al corpo della richiesta e invia l’header beta di fatturazione e l’header dell’ID del profilo.

Imposta bill_to: "user_profile" solo sulle richieste che il cliente ti chiede di effettuare: l’utilizzo di Claude che il cliente e i suoi utenti generano nel tuo prodotto. Non addebitare a un cliente il tuo utilizzo, come test, valutazioni o lavoro per altri clienti. La Claude API non può verificarlo per te, quindi è tua 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"}
        },
    )

Se la richiesta viene rifiutata, consulta Errori previsti.

Paghi tu

Per pagare tu stesso, ometti completamente billing_policy (in tal caso l’header beta di fatturazione è facoltativo):

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

oppure usa 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"}},
    )

Token OAuth per ciascuna connessione

Il tuo back end chiama la Claude API come l’account di servizio operatore della tua app (Passaggio 3). Per impostazione predefinita, qualsiasi richiesta autenticata come quell’account di servizio può addebitare ogni cliente collegato, passando un header con l’ID del profilo utente e includendo bill_to nelle richieste alla Messages API. Questo comportamento predefinito è chiamato “operator-only tokenless authentication” (autenticazione senza token solo operatore).

Per gestire deployment single-tenant del tuo prodotto, o ambienti sandbox controllati dal cliente, puoi ottenere token OAuth di accesso e di aggiornamento vincolati alla connessione, invece di usare l’autenticazione senza token solo operatore.

Per ogni connessione, lo scambio del codice nel Passaggio 8 restituisce il token di accesso proprio di quella connessione. Il token si autentica come il tuo account di servizio operatore, ma può addebitare solo il cliente di quella connessione. Scade entro 1 ora.

Per autenticare ciascuna connessione separatamente:

  • Usa l’accesso offline. Attiva Offline access per la tua app e richiedi offline_access nel Passaggio 5. Ogni connessione riceve quindi anche un refresh token, che il tuo back end usa per richiedere nuovi token di accesso. Senza di esso, il cliente deve approvare di nuovo per darti un nuovo token di accesso: esegui di nuovo i Passaggi da 5 a 8 con lo stesso scope.
  • Imposta un workspace predefinito. Scegli un workspace nella tua organizzazione in cui eseguire le richieste con questi token.
  • Facoltativamente, disattiva l’autenticazione senza token solo operatore. Per impostazione predefinita, puoi comunque addebitare un cliente collegato come il tuo account di servizio operatore (passando un header del profilo utente e bill_to), anche dopo la scadenza del token di accesso del cliente. Dopo aver disattivato l’autenticazione solo operatore, ogni richiesta che addebita un cliente deve autenticarsi con il token di accesso di quel cliente.
  • Usa billing:attribution. Solo questo scope fornisce a una connessione i propri token. Puoi comunque addebitare un cliente collegato come il tuo account di servizio operatore, come con org:billing_attribution, che è deprecato. Consulta Scope per una connessione di fatturazione.

Configura la tua app

Le richieste con il token di accesso di una connessione vengono eseguite in un workspace della tua organizzazione. Ogni app ne ha bisogno, anche se non usi questi token: finché la tua app non ha un workspace, lo scambio del codice nel Passaggio 8 viene rifiutato con unauthorized_client.

Un membro della tua organizzazione con il ruolo Admin apre la scheda Client authentication dell’app nella Console. Sotto l’account di servizio operatore, individua Default workspace for platform auth mode OAuth tokens (l’impostazione connection_token_workspace_id dell’app) e clicca su Choose workspace. Seleziona un workspace di cui l’account di servizio operatore (Passaggio 3) è membro. Il workspace non deve essere archiviato.

Per ottenere refresh token, attiva Offline access nella scheda Permissions dell’app. Una modifica agli scope dell’app richiede alcuni minuti per raggiungere auth.claude.com.

Scope per una connessione di fatturazione

Nel Passaggio 5, invia scope come billing:attribution. Per ottenere anche un “refresh token” (token di aggiornamento), invia billing:attribution offline_access.

Per modificare gli scope di un cliente già collegato, ad esempio per aggiungere offline_access, esegui di nuovo i Passaggi da 5 a 8 con il profilo utente esistente del cliente e il nuovo scope. Non è necessario scollegarlo prima. Lo scambio del codice restituisce un nuovo connection_id, e la nuova connessione sostituisce quella precedente. Consulta la nota nel Passaggio 8.

Un’app può avere contemporaneamente billing:attribution e lo scope deprecato org:billing_attribution. Aggiungi billing:attribution in Billing nella scheda Permissions dell’app. Se rimuovi org:billing_attribution da lì, non puoi aggiungerlo di nuovo. Una connessione che un cliente ha approvato con org:billing_attribution continua ad addebitare tramite il tuo account di servizio operatore finché la connessione non termina o finché non disattivi l’autenticazione solo operatore.

Memorizza i token

Lo scambio del codice restituisce i token una sola volta, quindi memorizzali nel Passaggio 8. La risposta contiene access_token, expires_in (al massimo 1 ora, in secondi) e connection_id. Se il cliente ha approvato offline_access, contiene anche refresh_token e refresh_token_expires_in. Un refresh token dura al massimo 1 anno, e un aggiornamento non ne estende la durata. Trascorso tale periodo, collega di nuovo il cliente.

Memorizza i token e i relativi orari di scadenza in un archivio di segreti che solo il servizio che esegue l’aggiornamento può leggere.

Se lo scambio viene rifiutato con unauthorized_client, error_description indica la causa, ad esempio un workspace mancante o archiviato. Il codice non viene consumato: correggi la causa e invia di nuovo lo stesso codice prima che scada.

Chiama Claude con il token di accesso di una connessione

Invia il token di accesso della connessione come bearer token nell’header Authorization, al posto della credenziale propria del tuo account di servizio operatore. Non inviare un header x-api-key. Nell’SDK di Anthropic, passa il token come auth_token, oppure imposta la variabile d’ambiente ANTHROPIC_AUTH_TOKEN.

Su /v1/messages e /v1/chat/completions, la richiesta viene addebitata al cliente di quella connessione. L’header anthropic-user-profile-id e billing_policy sono facoltativi. L’header beta di fatturazione ti serve solo con billing_policy.

Su questi due endpoint, non puoi pagare tu una richiesta con questo token. Usa il token solo su questi due endpoint, su /v1/messages/count_tokens e sugli endpoint Models. Invia ogni altra richiesta, e ogni richiesta che paghi tu, come il tuo account di servizio operatore, dal tuo back end. Ciò include una richiesta che usa le funzionalità di esecuzione del codice a pagamento, che non può addebitare un cliente.

La Claude API rifiuta queste richieste:

  • 400 invalid_request_error, senza codice di errore: la richiesta indicava un altro profilo utente o impostava bill_to: "self".
  • 403 permission_error, senza codice di errore: la richiesta è stata inviata a un endpoint Message Batches.
  • 401 authentication_error: il token è scaduto, un aggiornamento lo ha sostituito oppure la sua connessione è terminata. Dopo la fine di una connessione, la risposta può anche essere 403 user_profile_not_billable.

Aggiorna i token

Per rinnovare il token di accesso di una connessione, invia il suo refresh token all’endpoint token, https://auth.claude.com/v1/oauth/token, con l’autenticazione del client della tua app. Non inviare un parametro 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
    # Un 503 nel formato della Claude API con header retry-after è un rifiuto
    # che non usa il refresh token. Ogni altra risposta 5xx conta come persa.
    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.
    """
    # Questo lock funziona in un solo processo. Se il servizio ha repliche, usa un lock
    # condiviso da tutte.
    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"
        # Metti la connessione in sospeso prima che il refresh token lasci questo processo.
        # Se il processo si ferma prima che i nuovi token siano salvati, la sospensione resta.
        save_tokens(connection_id, replace(tokens, on_hold=True))
        issued_at = int(time.time())
        started = time.monotonic()
        # httpx non ritenta da solo. Non aggiungere retry: un retry tardivo chiude la
        # connessione.
        try:
            response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
            lost = is_lost(response)
        except (httpx.ConnectError, httpx.ConnectTimeout):
            # Nessuna connessione è stata stabilita, quindi il refresh token non ha mai lasciato il processo.
            save_tokens(connection_id, tokens)
            raise
        except httpx.TransportError:
            lost = True
        if lost:
            # La prima richiesta potrebbe aver usato il refresh token. Una seconda richiesta
            # è sicura solo entro il limite sopra, quindi inviane una subito o non inviarla
            # affatto.
            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:
                # Dopo qualsiasi risposta diversa da nuovi token non puoi sapere se la
                # prima richiesta ha avuto effetto, e una richiesta successiva non è sicura.
                raise hold_error(connection_id, "The second refresh failed.")
        if error_body(response).get("error") == "invalid_grant":
            # Scaduto, già usato, o la connessione è terminata. Inviarlo di nuovo
            # può chiudere la connessione.
            raise hold_error(connection_id, "The refresh returned invalid_grant.")
        if response.status_code != 200:
            # Un rifiuto che conserva il refresh token, quindi togli la sospensione.
            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"],
        )
        # Se la scrittura fallisce, ritenta la scrittura. Non rifare il refresh.
        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)
        # I nuovi token esistono solo in questo processo, e il refresh token salvato
        # è esaurito. Il record salvato è ancora in sospeso. L'errore contiene i nuovi
        # token, così il chiamante può salvarli quando il secret store torna disponibile.
        error = hold_error(
            connection_id,
            "The refresh succeeded, but the new tokens could not be saved.",
        )
        error.new_tokens = tokens
        raise error

La risposta contiene un nuovo access_token e un nuovo refresh_token. Il refresh token che hai inviato viene sostituito: non inviarlo di nuovo, salvo quanto indicato nell’elenco degli errori più avanti. Il token di accesso precedente smette di funzionare entro pochi minuti. Inizializzazione dei frammenti di codice dei token OAuth definisce le funzioni chiamate dall’esempio.

  • Memorizza il nuovo refresh token prima di usare il nuovo token di accesso.
  • Aggiorna i token di ogni connessione da un unico servizio, un aggiornamento alla volta. Se il servizio ha delle repliche, usa un lock condiviso da tutte. Un refresh token già usato che arriva di nuovo più di 30 secondi dopo il primo utilizzo termina la connessione. Ogni token viene revocato, il cliente viene mostrato come Unlinked e nessuna credenziale può addebitarlo finché non si collega di nuovo.
  • Disattiva i tentativi automatici per la richiesta di aggiornamento, nel tuo client HTTP e in qualsiasi proxy.

Se la prima richiesta con un refresh token non va a buon fine:

  • Non è stato possibile stabilire la connessione per la richiesta: il refresh token non è stato inviato. Riprova più tardi.
  • Una connessione interrotta, o qualsiasi risposta 5xx diversa dal 503 di questo elenco: non puoi sapere se la richiesta ha avuto effetto, quindi invia di nuovo lo stesso refresh token una sola volta.
    1. Invialo immediatamente, e solo se sono trascorsi meno di 30 secondi da quando hai inviato la prima richiesta.
    2. Se restituisce nuovi token, memorizzali e usa solo quelli. Se la prima richiesta ha avuto effetto, i suoi token, che non ti sono mai arrivati, vengono revocati.
    3. Se restituisce qualsiasi altra cosa o non riceve risposta, oppure se i 30 secondi sono trascorsi, non inviare di nuovo quel refresh token. Smetti di aggiornare quella connessione e collega di nuovo il cliente.
  • Un timeout: la richiesta potrebbe essere ancora in esecuzione. Non inviare di nuovo quel refresh token. Smetti di aggiornare quella connessione e collega di nuovo il cliente.
  • 429, oppure 503 con un header retry-after e "type": "error" al livello superiore del corpo: nulla è revocato. Attendi almeno quanto indicato dall’header e invia di nuovo lo stesso refresh token.
  • unauthorized_client o invalid_client: nulla è revocato. error_description indica la causa, ad esempio un workspace mancante, offline_access non più registrato per la tua app o un’asserzione client non riuscita. Correggila e invia di nuovo lo stesso refresh token.
  • invalid_scope: la richiesta ha inviato un parametro scope, oppure billing:attribution non è più registrato per la tua app. Nulla è revocato. Correggi la causa e invia di nuovo lo stesso refresh token.
  • invalid_grant: il refresh token è scaduto o è già stato usato, la connessione è terminata oppure l’organizzazione del cliente è sospesa. Smetti di aggiornare quella connessione e segui Collega di nuovo un cliente, che inizia con la verifica di un’eventuale sospensione.

Se una connessione interrotta, una risposta 5xx o un timeout ti ha indotto a smettere di aggiornare una connessione, sospendi anche gli aggiornamenti delle tue altre connessioni. Quando riprendi, aggiorna prima una connessione e riprendi le altre solo dopo che quell’aggiornamento è riuscito o ha ricevuto una risposta 4xx.

Esegui un agente in una sandbox

Fornisci a una “sandbox” (ambiente isolato) solo il token di accesso, mai il refresh token. Il tuo back end esegue l’aggiornamento e invia ogni nuovo token di accesso alla sandbox. Decide quale cliente serve una sandbox in base all’identità della sandbox stessa, come l’identità del suo pod, e mai in base a un valore inviato dalla sandbox. Invia a una sandbox solo il token di quel cliente. La sandbox non deve poter ottenere un JWT che corrisponda a una delle tue regole di federazione o all’autenticazione del client della tua app. Non fornirle alcun token di identità montato né alcun accesso a un server di metadati cloud.

Claude Code, il Claude Agent SDK e l’SDK di Anthropic possono leggere il token da un file di credenziali in un profilo di configurazione (consulta File di configurazione del profilo). Nella sandbox, crea una directory di configurazione con questo profilo. Non aggiungervi un client_id: se presente, l’SDK tenta di aggiornare il token autonomamente.

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

Scrivi il token di accesso come credentials/customer.json nella stessa directory, prima dell’avvio dell’agente e dopo ogni aggiornamento. expires_at è l’orario di scadenza in secondi Unix. Scrivi un nuovo file con modalità 0600 e rinominalo sovrascrivendo quello vecchio:

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

Imposta ANTHROPIC_CONFIG_DIR sulla directory di configurazione e ANTHROPIC_PROFILE su customer. Rimuovi ogni altra credenziale nella sandbox, come ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN e l’impostazione apiKeyHelper di Claude Code, perché ciascuna può avere la precedenza sul profilo. L’agente rilegge il file negli ultimi 2 minuti prima di expires_at e dopo una risposta 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}
    # Rinomina un file completato nella destinazione, così l'agente non legge mai un file a metà.
    # mkstemp imposta la modalità 0600 con l'utente corrente come proprietario, quindi esegui come
    # utente dell'agente.
    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")

Collega di nuovo un cliente

Collega di nuovo un cliente nei seguenti casi:

  • Un aggiornamento ha restituito invalid_grant.
  • Hai perso un refresh token, oppure ne è trapelato uno.
  • Hai perso la risposta del Passaggio 8 per billing:attribution offline_access, oppure il Passaggio 8 ha restituito invalid_grant per tale connessione.
  • Un refresh token è prossimo alla scadenza.

Segui questi passaggi:

  1. Nella tua pagina User profiles, verifica se il cliente viene mostrato come Linked. Dopo invalid_grant, chiedi prima al tuo team di riferimento Anthropic se l’organizzazione del cliente è sospesa: dopo la fine di una sospensione, il refresh token in tuo possesso torna a funzionare. Se ogni connessione restituisce invalid_grant contemporaneamente, cerca una causa dalla tua parte, come un workspace archiviato, prima di scollegare chiunque.
  2. Se il cliente viene mostrato come Linked, scollegalo, come descritto in Scollegare un cliente. Lo scollegamento revoca i token della connessione. Fallo quando un amministratore dell’organizzazione del cliente è pronto ad approvare, perché l’addebito tramite la connessione si interrompe finché non approva.
  3. Esegui di nuovo i Passaggi da 5 a 8 con il profilo utente esistente del cliente. Memorizza il nuovo ID di connessione e i nuovi token al posto di quelli precedenti.

Disattiva l’autenticazione solo operatore

Per impedire che le richieste che si autenticano solo come il tuo account di servizio operatore addebitino i clienti, attiva Disable operator-only tokenless authentication (l’impostazione disable_operator_only_auth dell’app). Si trova nella scheda Client authentication dell’app, sotto l’account di servizio operatore. La tua app deve avere gli scope billing:attribution e offline_access e un workspace per i suoi token OAuth. Prima di attivarla, assicurati che ogni cliente collegato abbia approvato billing:attribution offline_access e che le tue richieste con i loro token di accesso funzionino. Mentre è attiva, solo il token di accesso di una connessione billing:attribution può addebitare il cliente di quella connessione. Una richiesta che si autentica solo come l’account di servizio e imposta bill_to: "user_profile" viene rifiutata con 403 user_profile_not_billable. Il cliente viene comunque mostrato come Linked, quindi monitora questo errore nei tuoi log. L’account di servizio può comunque gestire i profili utente e inviare le richieste che paghi tu. Puoi disattivare di nuovo l’impostazione.

Inizializzazione dei frammenti di codice dei token OAuth

Gli esempi in questa sezione condividono la seguente configurazione. Definisce:

  • le importazioni, che includono il pacchetto httpx
  • il client ID della tua app e il tipo di asserzione client
  • ConnectionTokens, che contiene i token di una connessione, i relativi orari di scadenza e il suo contrassegno on_hold
  • RefreshOnHold, l’errore che refresh_connection() solleva quando un refresh token non deve essere inviato di nuovo: potrebbe essere già stato usato, oppure l’endpoint token ha risposto invalid_grant. refresh_connection() lo solleva anche a ogni chiamata successiva, finché non rimuovi on_hold nei token memorizzati, ad esempio dopo la fine di una sospensione. Quando un aggiornamento è riuscito e solo il tuo archivio di segreti ha rifiutato la scrittura, il suo new_tokens contiene i token da memorizzare.
  • client_assertion(), che legge il JWT del tuo provider di identità dal file indicato da ANTHROPIC_IDENTITY_TOKEN_FILE. Il claim aud del JWT deve essere l’audience nelle impostazioni di autenticazione del client della tua app.
  • load_tokens() e save_tokens(), che scrivi per il tuo archivio di segreti
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"
# copia da platform.claude.com dopo aver registrato la tua app OAuth.
CLIENT_ID = "YOUR_CLIENT_ID"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
REFRESH_MARGIN_SECONDS = 600
# Un refresh che va in timeout qui perde i nuovi token, quindi concedi 10 secondi per la
# risposta. Una connessione che non può essere stabilita fallisce entro 2.
REQUEST_TIMEOUT = httpx.Timeout(10, connect=2)
# Una seconda richiesta deve partire entro questo tempo dalla prima, o non partire affatto. La
# pagina indica 30 secondi, ma resta sotto il read timeout di REQUEST_TIMEOUT: una
# richiesta andata in timeout non deve essere inviata di nuovo.
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: il refresh token potrebbe essere stato usato. Non inviarlo di nuovo.
    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.")

Gestione delle connessioni

Visualizzare i clienti nella Console

Oltre alla pagina delle app OAuth, puoi visualizzare tutti i tuoi profili utente nella pagina User profiles nella Console. In quell’elenco e nella pagina di dettaglio di ciascun profilo utente, Your spend è il tuo costo per le richieste di quel profilo utente. È il costo prima che Anthropic applichi eventuali crediti. Queste pagine chiamano “link” una connessione: un profilo utente con una connessione attiva riporta Linked, mentre uno la cui connessione è terminata riporta Unlinked.

Clicca su un profilo utente per una visualizzazione più dettagliata del suo utilizzo negli ultimi 7, 28 o 90 giorni.

Monitorare l’utilizzo di ciascun cliente

La Claude Console e l’API Usage and Cost Analytics riportano entrambe l’utilizzo per ciascun profilo utente. Entrambe conteggiano le richieste che paghi tu e le richieste che paga il tuo cliente. Nessuna delle due mostra quanto ha pagato il cliente né le tariffe del cliente.

Nella Console, la pagina User profiles elenca Requests, Tokens e Your spend per ciascun profilo utente negli ultimi 28 giorni. Una richiesta pagata dal tuo cliente si aggiunge a Requests e Tokens del profilo e non aggiunge nulla a Your spend.

Chiama l’API con una credenziale della Admin API, come un token di accesso OAuth con lo scope org:admin o una chiave della Admin API. Non usare il tuo account di servizio operatore (Passaggio 3). La sua regola di federazione concede workspace:developer per impostazione predefinita, non org:admin. Lo scope org:admin copre l’intera Admin API, quindi non aggiungerlo all’account di servizio operatore.

Per ottenere report per profilo utente tramite l’API, chiama il suo endpoint di utilizzo o il suo endpoint dei costi. Per ottenere una riga per ciascun profilo utente, raggruppa solo per user_profile_id e ometti time_bucket_width. Ottiene una riga solo un profilo utente che ha utilizzo nell’intervallo di tempo richiesto. Un’ulteriore riga ha un user_profile_id nullo. Contiene l’utilizzo che non indicava alcun profilo e l’utilizzo misurato al di fuori delle richieste, come il tempo dei container di esecuzione del codice.

Sull’endpoint dei costi, una richiesta pagata dal tuo cliente aggiunge 0 ad amount e il suo prezzo di listino a list_amount. Il campo amount è la stessa misura di Your spend. L’API non ha alcun campo, filtro o valore group_by[] che indichi chi ha pagato. Una riga con un amount pari a 0 e un list_amount superiore a 0 di solito indica che il cliente ha pagato ogni richiesta in quella riga.

Non usare questi dati per interrompere l’utilizzo di un cliente a un importo da te scelto. Né la Console né l’API riportano i dati in tempo reale. I dati della Console si aggiornano circa una volta all’ora, e una richiesta può impiegare alcune ore per comparire. Per il ritardo dell’API, consulta Aggiornamento dei dati. Tetti di spesa indica cosa fanno i limiti propri del cliente.

Scollegare un cliente

Per scollegare un cliente nella Console, usa l’elenco nella pagina User profiles oppure il pulsante Unlink in alto a destra nella pagina di dettaglio di un profilo utente.

Per scollegare un cliente dal tuo back end, invia l’ID di connessione che hai memorizzato nel Passaggio 8 all’endpoint di revoca, con la stessa autenticazione del client usata per lo scambio del codice. Per indicare invece la connessione tramite il suo profilo utente, invia user_profile_id al posto di 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 delle connessioni terminate da questa richiesta. La lista è vuota se la
    # connessione era già terminata o l'ID è sconosciuto.
    return response.json()["revoked_connection_ids"]

auth.claude.com risponde con HTTP 200 e revoked_connection_ids, gli ID delle connessioni terminate da questa richiesta. L’elenco è vuoto se la connessione è già terminata, quindi puoi ripetere in sicurezza una richiesta che invia connection_id. È vuoto anche se l’ID è sconosciuto, quindi un elenco vuoto non dimostra che la connessione esistesse. Consulta Revoca per gli altri parametri ed Errori dall’endpoint di revoca.

Dopo la fine della connessione, il profilo utente viene mostrato come Unlinked e una richiesta che imposta bill_to: "user_profile" per questo cliente riceve user_profile_not_billable. Puoi comunque servire il cliente a tue spese con bill_to: "self". Dopo il collegamento descrive ciò che vede il tuo cliente, e Email sul collegamento e lo scollegamento indica quale modalità di scollegamento gli invia un’email.

Collegare un cliente a un’altra organizzazione Claude

Per collegare il profilo utente di un cliente a un’altra organizzazione Claude, scollega il cliente e poi collegalo di nuovo.

Dopo lo scollegamento, le richieste che addebiti a questo cliente vengono rifiutate. Ciò dura finché un utente non approva per l’altra organizzazione e tu non scambi il codice nel Passaggio 8. Segui questi passaggi quando quell’utente è pronto ad approvare:

  1. Salta questo passaggio se il tuo cliente ha già scollegato la tua app nella sua pagina Linked platforms. Altrimenti, scollega il cliente, come descritto in Scollegare un cliente. Il profilo utente viene quindi mostrato come Unlinked nella tua pagina User profiles.
  2. Esegui di nuovo i Passaggi da 5 a 8 con lo stesso profilo utente. Per il Passaggio 7, l’utente ha bisogno di un account con il ruolo Amministratore o Fatturazione nell’altra organizzazione. Fai approvare all’utente per quell’organizzazione.
  3. Memorizza il nuovo ID di connessione al posto di quello precedente. Se usi i token della connessione, fai lo stesso con i nuovi token.

Finché il cliente non viene scollegato, la pagina di approvazione consente a un utente di approvare solo per l’organizzazione già collegata.

Un tetto di spesa appartiene a un’organizzazione cliente e alla tua app, quindi il tetto della prima organizzazione non viene trasferito. Tetti di spesa riporta le regole.

Errori previsti

Quando una richiesta imposta bill_to: "user_profile", Anthropic addebita il tuo cliente oppure rifiuta la richiesta. Non addebita mai silenziosamente a te al suo posto. Su /v1/messages il codice dell’elenco seguente si trova in error.details.error_code. Su /v1/chat/completions ricevi lo stesso stato HTTP e lo stesso messaggio in formato OpenAI, senza il codice:

  • 403 permission_error, user_profile_not_billable: Anthropic non può addebitare questo cliente per questa richiesta, e la risposta non indica il motivo. Non ritentabile, tranne nei primi 10 secondi dopo una nuova connessione. Prima di chiedere al cliente di ricollegarsi, consulta Cause di user_profile_not_billable: ricollegarsi risolve solo alcune di esse. Puoi comunque servire il cliente a tue spese inviando di nuovo la richiesta con bill_to: "self". Nell’SDK di Anthropic, gestisci user_profile_not_billable tramite la classe di errore per lo stato 403, che è PermissionDeniedError. Questa corrisponde anche ad altri errori 403, quindi verifica anche il codice di errore.
  • 402 billing_error, linked_organization_billing_unavailable: Anthropic al momento non può addebitare l’organizzazione del cliente (ad esempio, è sospesa, oppure il suo credito si esaurisce dopo che Claude ha iniziato una risposta). La risposta non indica il motivo. Un cliente che non ha credito quando arriva la richiesta riceve invece linked_organization_spend_limit_reached. Non ritentabile. Chiedi al cliente di controllare il proprio account Claude Platform. Puoi comunque servirlo a tue spese inviando di nuovo la richiesta con bill_to: "self".
  • 402 billing_error, linked_organization_spend_limit_reached: l’organizzazione del cliente ha raggiunto un limite di spesa che ha impostato. Il limite è il tetto di spesa che si applica alla tua app oppure il limite di spesa mensile per l’intera organizzazione. La Claude API invia lo stesso codice quando l’organizzazione non ha alcun credito che possa pagare la richiesta. La risposta non indica quale sia la causa. La richiesta è stata rifiutata prima che Claude iniziasse una risposta. Non ritentabile. Puoi comunque servire il cliente a tue spese inviando di nuovo la richiesta con bill_to: "self". Chiedi al cliente di controllare questi elementi nella Claude Console:
    • Il tetto di spesa per la tua app: nella pagina della tua app in Linked platforms, può impostare o aumentare il tetto di spesa. Un tetto impostato lì sostituisce qualsiasi tetto predefinito che ha impostato per tutte le piattaforme collegate.
    • Il Limite di spesa mensile dell’organizzazione: nella sezione Limiti di spesa, può aumentarlo.
    • Il saldo del credito: nella propria pagina Fatturazione, può vedere il proprio saldo del credito e acquistare credito. Alcuni crediti non possono pagare queste richieste: consulta Quali crediti possono pagare.
  • 503 overloaded_error: Anthropic non è riuscita a confermare in questo momento se il cliente può essere addebitato. Riprova con backoff e rispetta l’header retry-after. La richiesta non è stata servita né addebitata.
  • 400 invalid_request_error, user_profile_required: hai impostato bill_to: "user_profile" senza l’header anthropic-user-profile-id. Una richiesta di questo tipo necessita dell’header, a meno che non usi il token di accesso di una connessione e l’header sia facoltativo. Per sapere se l’header è facoltativo, consulta la nota in Chiama Claude con il token di accesso di una connessione.
  • 400 invalid_request_error, senza codice di errore: l’header anthropic-user-profile-id contiene un ID non valido o che non è un profilo utente della tua organizzazione.
  • 400 invalid_request_error, senza codice di errore: la richiesta si è autenticata con il token di accesso di una connessione e ha impostato bill_to: "self" oppure ha indicato un profilo utente diverso da quello a cui il token è limitato. Consulta Chiama Claude con il token di accesso di una connessione.

Su /v1/messages e /v1/chat/completions, il token di accesso di una connessione non può inviare una richiesta che paghi tu. Per inviare di nuovo una richiesta rifiutata con bill_to: "self", autenticati dal tuo back end con la credenziale propria del tuo account di servizio operatore. Chiama Claude con il token di accesso di una connessione elenca i rifiuti relativi al token stesso.

Una risposta con esito positivo non indica a chi è stato addebitato il costo, quindi tieni un registro tuo delle richieste che hai inviato con bill_to: "user_profile".

Cause di user_profile_not_billable

Verificale in quest’ordine:

  • La tua richiesta. La richiesta deve autenticarsi come l’account di servizio operatore della tua app OAuth (Passaggio 3). Anche il token di accesso di una connessione si autentica come quell’account di servizio. Una richiesta che si autentica in qualsiasi altro modo viene rifiutata. Ne sono esempi un account di servizio diverso e una chiave API non associata a quell’account di servizio. Se l’header anthropic-user-profile-id indica uno dei tuoi profili che non è collegato, la richiesta viene rifiutata. Se la credenziale o l’header non sono corretti, correggi la richiesta. Una nuova connessione non risolve il problema.
  • La connessione. Il cliente non si è collegato tramite questa app, oppure la connessione è terminata: l’ha terminata un amministratore della sua organizzazione o della tua, oppure il tuo back end. Una connessione terminata viene mostrata come Unlinked nella tua pagina User profiles. Un profilo collegato solo tramite la tua app di test non è collegato alla tua app di produzione. Smetti di addebitare quel cliente finché non si collega. Il token di accesso di una connessione è limitato a quella connessione, quindi dopo che il cliente si è collegato di nuovo, usa il token di accesso della nuova connessione. Se la tua app ha disattivato l’autenticazione solo operatore, puoi addebitare un cliente solo con il token di accesso della sua connessione. In tal caso, un cliente per cui non possiedi alcun token funzionante di una connessione billing:attribution viene mostrato come Linked, ma deve approvare di nuovo, come descritto in Collega di nuovo un cliente.
  • L’organizzazione del cliente. Deve essere un cliente idoneo. Non puoi verificarlo dalla tua parte, quindi chiedi al tuo team di riferimento Anthropic.

Una nuova connessione di solito funziona subito, ma possono essere necessari circa 10 secondi dopo lo scambio del Passaggio 8. Se una richiesta viene rifiutata con user_profile_not_billable in quei 10 secondi, inviala di nuovo. Dopo di che, attendere o ritentare non cambia il risultato. Registra l’intero error.message e l’header di risposta request-id di ogni richiesta rifiutata. Se un cliente la cui connessione viene mostrata come Linked viene ancora rifiutato e la tua richiesta è corretta, invia il request-id di una richiesta rifiutata al tuo team di riferimento Anthropic, in modo che Anthropic possa verificare il motivo del rifiuto.

La prospettiva del tuo cliente

Collegamento

Il tuo utente approva su auth.claude.com dopo che la tua app lo reindirizza nel Passaggio 6. Il Passaggio 7 elenca le schermate della pagina di approvazione. Ogni schermata mostra il nome della tua app e ha un pulsante Cancel. Ecco cosa fa l’utente in ciascuna schermata:

  • Select an organization: L’utente sceglie quale delle sue organizzazioni Claude collegare. La pagina mostra questa schermata solo se l’utente ha la possibilità di scegliere un’organizzazione.
  • How billing works: L’utente legge la schermata e clicca su Continue.
  • Set a monthly spend limit: L’utente inserisce un limite per la tua app in dollari USA interi e clicca su Continue. Il campo dell’importo è inizialmente vuoto, quindi la pagina non sceglie un limite per l’utente. Continue without a limit non salva alcun nuovo limite, e un tetto o un valore predefinito che il cliente ha salvato in precedenza continua ad applicarsi. Il limite inserito dall’utente è il tetto di spesa descritto in Tetti di spesa. Questa schermata è diversa mentre la tua app è in fase di test: consulta Mentre la tua app è in fase di test.
  • L’ultima schermata: Questa schermata elenca ciò che la tua app potrà fare, incluso il limite scelto dall’utente. L’utente clicca su Link and authorize.

La pagina di approvazione usa l’account Claude con cui è stato effettuato l’accesso nel browser e propone solo le organizzazioni Claude di quell’account. Quell’account potrebbe non essere quello che il tuo utente si aspetta, ad esempio un account personale invece di uno di lavoro. La tua app non può scegliere l’account. I parametri OpenID Connect prompt=select_account e login_hint non cambiano l’account usato dalla pagina.

Dopo il collegamento

I tuoi clienti gestiscono le proprie connessioni nella pagina Linked platforms nella Claude Console. Possono scollegare la tua app in qualsiasi momento. Anthropic non ti avvisa quando lo fanno: non ricevi alcun evento webhook né alcuna email.

Dopo che un cliente si è scollegato, le richieste che addebiti a quel cliente vengono rifiutate con 403 user_profile_not_billable (consulta Cause di user_profile_not_billable). Il profilo utente del cliente viene mostrato come Unlinked nella tua pagina User profiles nella Console. Per ricollegarsi, esegui di nuovo i Passaggi da 5 a 8 con il profilo utente esistente del cliente.

Email sul collegamento e lo scollegamento

Le email di Anthropic sul collegamento e lo scollegamento vengono inviate ai membri dell’organizzazione del tuo cliente che hanno il ruolo Amministratore o Fatturazione. Ogni email rimanda alla pagina Linked platforms del cliente. L’invio di un’email da parte di Anthropic dipende dall’evento:

  • Quando il cliente collega la tua app: Anthropic invia un’email quando scambi il codice nel Passaggio 8. Non invia nulla per un’approvazione il cui codice non scambi mai. Non invia nulla nemmeno quando un utente approva di nuovo mentre il cliente è ancora collegato.
  • Quando il cliente scollega la tua app: Anthropic invia un’email. L’email non indica la persona che ha scollegato la tua app.
  • Quando scolleghi il cliente dal tuo back end: Anthropic invia un’email.
  • Quando scolleghi il cliente nella Console: Anthropic non invia alcuna email.

Anthropic non garantisce che un’email venga inviata o recapitata. Avvisa tu stesso il tuo cliente quando lo scolleghi. Non fare affidamento su queste email per comunicare a un cliente che è collegato.

Tetti di spesa

Il tuo cliente può impostare un tetto di spesa mensile per la tua app, in dollari statunitensi (USD). La pagina di approvazione chiama questo tetto limite di spesa mensile, e l’utente che effettua il collegamento può impostarlo lì (consulta Collegamento). È distinto dal Limite di spesa mensile dell’organizzazione, che si applica all’intera organizzazione. Non puoi leggere il tetto di un cliente, né quanto ne ha utilizzato.

Quando la spesa del cliente tramite la tua app raggiunge il tetto, la Claude API rifiuta con un 402 le richieste che gli addebiti. Consulta Errori previsti. I rifiuti durano fino alle 00:00 UTC del primo giorno del mese successivo, oppure finché il cliente non aumenta o rimuove il tetto. Una modifica al tetto può richiedere circa un minuto per essere applicata.

Dopo il collegamento, un membro dell’organizzazione del cliente con il ruolo Amministratore o Fatturazione gestisce i tetti nella pagina Linked platforms nella Console:

  • Impostare o modificare un tetto: clicca sulla tua app, quindi su Set spend cap o Edit spend cap.
  • Impostare un valore predefinito: in Default spend cap, clicca su Set default o Edit. Ogni app collegata che non ha un proprio tetto può spendere ogni mese fino al valore predefinito. Le app non lo condividono.
  • Rimuovere un tetto: clicca sulla tua app, su Edit spend cap e quindi su Remove cap. La tua app usa quindi il valore predefinito. Se non esiste un valore predefinito, la tua app non ha alcun tetto.

Il tetto minimo è $0 USD, che rifiuta ogni richiesta che addebiti a quel cliente. La Console accetta importi in dollari interi, senza un massimo effettivo. Il tetto conteggia i costi dei token e le tariffe della ricerca web ai prezzi di listino, prima di qualsiasi sconto negoziato. La fattura del cliente può differire dall’importo conteggiato dal tetto.

Un tetto può essere superiore al Limite di spesa mensile dell’organizzazione, che il cliente imposta in Limiti di spesa. La Claude API rifiuta le richieste che addebiti al cliente quando viene raggiunto uno dei due.

Mentre la tua app è in fase di test

Questi limiti si applicano ogni volta che qualcuno collega la tua app o ne modifica il tetto mentre l’app è in fase di test, in revisione o non approvata:

In fase di test, in revisione o non approvataDopo che l’app è attiva
Un limite di spesa mensile nella pagina di approvazioneObbligatorio, $50 USD o menoFacoltativo
Il campo dell’importo nella pagina di approvazioneParte da $50 USDInizialmente vuoto
Continue without a limit nella pagina di approvazioneNon disponibileDisponibile
Rimozione del tetto nella ConsoleNon possibilePossibile
Il tetto massimo che un cliente può impostare$50 USDNessun massimo effettivo

Una volta che la tua app è attiva, un tetto che un cliente ha salvato in precedenza rimane in vigore. Il cliente può quindi aumentarlo o rimuoverlo.

Supportare i tuoi clienti

Fornisci supporto ai tuoi clienti per tutto ciò che riguarda la tua app, incluso l’utilizzo di Claude che addebiti loro. Anthropic offre ai tuoi clienti la pagina di approvazione e la pagina Linked platforms nella Claude Console. Nella pagina Linked platforms, un membro con il ruolo Amministratore o Fatturazione può vedere quanto è costata la tua app all’organizzazione questo mese. Può inoltre impostare un tetto di spesa mensile per la tua app e scollegarla. Tutte le altre domande sulla tua app devono essere rivolte a te, quindi indica ai tuoi clienti come contattarti.

Inizializzazione dei frammenti di codice

Gli esempi Python in questa pagina condividono la seguente configurazione, che scrivi una sola volta. Definisce:

  • le importazioni
  • il client ID e il redirect URI della tua app
  • il valore dell’header beta di fatturazione
  • un client della Claude API che si autentica come il tuo account di servizio
  • client_assertion, che restituisce l’asserzione client che il tuo back end invia a auth.claude.com
# Gli esempi Python presuppongono l'inizializzazione e le variabili seguenti
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"
# copia da platform.claude.com dopo aver registrato la tua 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. L'SDK scambia il JWT di identità del tuo workload con un token di accesso
# e lo aggiorna, così non gestisci mai direttamente "Bearer <access token>".
client = anthropic.Anthropic()

# Client assertion per auth.claude.com: il JWT di identità stesso, riletto a
# ogni chiamata perché il file ruota. Se le impostazioni di autenticazione client
# della tua app indicano un'audience diversa dalla regola di federazione, punta a
# un secondo file di token: IdentityTokenFile("/path/to/other/token").
client_assertion = IdentityTokenFile()

Questa pagina ti è stata utile?