---
title: Linked billing
url: https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections
description: 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.
---

<Warning>
  Claude Platform OAuth è un Beta Service: software in anteprima fornito ai sensi del tuo accordo con Anthropic, come i [Termini di servizio commerciali](https://www.anthropic.com/legal/commercial-terms), e i [Termini specifici del servizio](https://www.anthropic.com/legal/service-specific-terms). Endpoint, parametri e comportamento possono cambiare durante la beta. Potrebbe non essere adatto all’uso in produzione.
</Warning>

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`](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude) 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](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope), 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](https://platform.claude.com/docs/it/about-claude/pricing#code-execution-tool) (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](https://platform.claude.com/docs/it/build-with-claude/batch-processing) (`/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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

## Processo di configurazione

Esegui questi tre passaggi una sola volta. Registrano la tua app presso Anthropic. Successivamente, [Quale profilo utente collegare](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link) 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](https://platform.claude.com/settings/oauth-apps) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#publish-your-app) ed è attiva, l’impostazione riporta **Any Claude user**.

<Note>
  Un’organizzazione può registrare diverse app OAuth, ad esempio una per la produzione e una per i test. Ogni app ha le proprie connessioni: un cliente che collega la tua app di test non è collegato alla tua app di produzione. Mantieni Linked billing su un’unica app di produzione per tutta la durata della tua integrazione.
</Note>

### 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.

<Note>
  La tua app si autentica agli endpoint PAR, token e di revoca con una variante del metodo `private_key_jwt` (RFC 7523): con ogni richiesta, il tuo back end invia una “client assertion” (asserzione client), un JWT emesso dal tuo provider di identità. `auth.claude.com` verifica la firma del token con le chiavi registrate per quell’emittente e lo confronta con le condizioni sul subject o sui claim che imposti qui. Per i claim che un’asserzione client deve contenere, consulta [Claim dell’asserzione client](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#client-assertion-claims).
</Note>

### 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](https://platform.claude.com/docs/it/manage-claude/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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection). Prima di collegare i clienti, [imposta un workspace](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) 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.

### Quale profilo utente collegare

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](https://platform.claude.com/docs/it/manage-claude/user-profiles).

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`](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#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_id`](https://platform.claude.com/docs/it/api/messages/create) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#code-snippet-initialization). 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/branding-samples#buttons)). 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).

<Frame>
  ![Diagramma di sequenza dei Passaggi da 5 a 8: la richiesta di approvazione, l'approvazione dell'utente e lo scambio con un connection ID (ID di connessione)](https://platform.claude.com/docs/it/images/oauth-apps-billing-connection-flow.svg)
</Frame>

### 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link).

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/user_profiles \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "name": "Example Customer Inc.",
      "external_user_details": {"reference_id": "your-customer-id-123"}
    }'
  ```

  ```bash CLI
  ant user-profiles create \
    --name "Example Customer Inc." \
    --external-user-details.reference-id your-customer-id-123
  ```

  ```python Python
  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")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const profile = await client.userProfiles.create({
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  });

  console.log(profile.id); // "uprof_..."
  ```

  ```csharp C#
  AnthropicClient client = new();

  var profile = await client.UserProfiles.Create(
      new()
      {
          Name = "Example Customer Inc.",
          ExternalUserDetails = new() { ReferenceID = "your-customer-id-123" },
      }
  );

  Console.WriteLine(profile.ID);
  ```

  ```go Go
  client := anthropic.NewClient()

  profile, err := client.UserProfiles.New(context.Background(), anthropic.UserProfileNewParams{
  	Name: anthropic.String("Example Customer Inc."),
  	ExternalUserDetails: anthropic.UserProfileExternalUserDetailsParams{
  		ReferenceID: anthropic.String("your-customer-id-123"),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(profile.ID)
  ```

  ```java Java
  import com.anthropic.models.userprofiles.UserProfileCreateParams;
  import com.anthropic.models.userprofiles.UserProfileExternalUserDetailsParams;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = UserProfileCreateParams.builder()
          .name("Example Customer Inc.")
          .externalUserDetails(UserProfileExternalUserDetailsParams.builder()
              .referenceId("your-customer-id-123")
              .build())
          .build();
      var profile = client.userProfiles().create(params);

      IO.println(profile.id());
  }
  ```

  ```php PHP
  $client = new Client();

  $profile = $client->userProfiles->create(
      name: 'Example Customer Inc.',
      externalUserDetails: ['referenceID' => 'your-customer-id-123'],
  );

  echo $profile->id, PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  profile = client.user_profiles.create(
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  )

  puts(profile.id)
  ```
</CodeGroup>

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](https://platform.claude.com/docs/it/manage-claude/user-profiles#decide-who-gets-a-profile).

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

<Note>
  Ogni richiesta di creazione genera un nuovo profilo, anche con lo stesso `reference_id` (il tuo ID per il cliente), quindi riutilizza l’ID memorizzato invece di creare un profilo a ogni tentativo di connessione.
</Note>

### 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.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/par \
    -H "content-type: application/json" \
    -d '{
      "response_type": "code",
      "client_id": "YOUR_CLIENT_ID",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "scope": "billing:attribution",
      "connection_type": "organization_shared",
      "connection_auth_target": "platform",
      "user_profile_id": "uprof_01HV9Z",
      "state": "RANDOM_STATE",
      "code_challenge": "BASE64URL_SHA256_OF_VERIFIER",
      "code_challenge_method": "S256",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  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)
  ```
</CodeGroup>

`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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection). 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.

<Note>
  La persona che approva deve essere un amministratore dell’organizzazione Claude del cliente: un membro con il ruolo Amministratore o Fatturazione.
</Note>

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.

```python
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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connecting).

   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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

<Note>
  La connessione appartiene all’intera organizzazione Claude, non all’utente che l’ha approvata. Se quell’utente lascia l’organizzazione, la connessione rimane attiva. Qualsiasi amministratore dell’organizzazione del cliente o della tua può terminare la connessione in qualsiasi momento, e lo stesso può fare il tuo back end.
</Note>

### 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

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.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d '{
      "grant_type": "authorization_code",
      "code": "AUTH_CODE",
      "code_verifier": "ORIGINAL_CODE_VERIFIER",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "client_id": "YOUR_CLIENT_ID",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  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"]
  ```
</CodeGroup>

La risposta contiene l’ID di connessione e [il token di accesso della connessione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection), 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints). Consulta [Aggiorna le chiamate a Claude](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude) ed [Errori previsti](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#expected-errors) 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`](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#code-exchange-unauthorized-client).

<Note>
  Un utente può approvare di nuovo per un profilo utente già collegato. L’esito dipende dagli scope:

  * Nuova approvazione per lo stesso profilo utente e gli stessi scope: la connessione rimane e la risposta del token restituisce lo stesso `connection_id` e un nuovo token di accesso. Fa eccezione una connessione con `billing:attribution offline_access`: lo scambio del codice restituisce `invalid_grant`, la connessione rimane com’era e [Collega di nuovo un cliente](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again) spiega cosa fare.
  * Nuova approvazione per lo stesso profilo utente con altri scope, ad esempio `billing:attribution offline_access` dopo `billing:attribution`: lo scambio del nuovo codice crea una nuova connessione con un nuovo `connection_id`, che sostituisce quella precedente. I token di una precedente connessione `billing:attribution` vengono revocati. Memorizza il nuovo `connection_id` al posto di quello precedente. Se lo scambio non va a buon fine con una risposta 5xx, esegui di nuovo i Passaggi da 5 a 8. [Scope per una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection) spiega quando è necessario.
  * Dopo la revoca di una connessione, puoi collegare di nuovo lo stesso profilo utente.
</Note>

### 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints).
* 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing) 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](https://platform.claude.com/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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#errors) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).
   * 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer), 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:

| Verifica                                           | Dove                                                                                                                                                          | Correzione                                                                                                   |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| L’app ha un account di servizio operatore          | **Operator service account** nella scheda **Client authentication** dell’app                                                                                  | Selezionane uno e clicca su **Save**. Il Passaggio 3 spiega come configurarne uno.                           |
| Il workspace dell’app non è mancante né archiviato | [Configura la tua app](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) | Scegli 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) e [Aggiorna i token](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection).

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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token). 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.

<Warning>
  Verifica che l’header indichi il profilo del cliente a cui si riferisce la richiesta. Per impostazione predefinita, la credenziale propria del tuo account di servizio operatore può addebitare ogni cliente collegato tramite questa app. Se una richiesta con quella credenziale indica un profilo diverso collegato tramite questa app, Anthropic addebita l’organizzazione di quel profilo e nessun errore te lo segnala. Il [token di accesso di una connessione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) può addebitare solo il proprio cliente.
</Warning>

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à.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: user_profile
  YAML
  ```

  ```python Python
  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"}
          },
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "user_profile" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy non è ancora nei tipi dell'SDK
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "user_profile" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "user_profile",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "user_profile")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'user_profile'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "user_profile" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

Se la richiesta viene rifiutata, consulta [Errori previsti](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

### Paghi tu

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

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}'
  ```

  ```python Python
  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,
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  });

  console.log(message.content);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var message = await client.Messages.Create(
      new MessageCreateParams
      {
          Model = Model.ClaudeSonnet5_5,
          MaxTokens = 1024,
          Messages = [new UserMessageParam { Content = "Hello, Claude" }],
          UserProfileID = "uprof_01HV9Z",
      }
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
  	},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.models.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .userProfileId("uprof_01HV9Z")
          .build();
      var message = client.messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      userProfileID: 'uprof_01HV9Z',
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  )

  puts(message.content)
  ```
</CodeGroup>

oppure usa `bill_to: "self"`:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "self"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: self
  YAML
  ```

  ```python Python
  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"}},
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "self" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy non è ancora presente nei tipi dell'SDK
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "self" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "self",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "self")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'self'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "self" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

## 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**](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection).

### 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`.

<Note>
  L’archiviazione del workspace predefinito revoca ogni token che viene eseguito al suo interno e non può essere annullata. Per passare a un altro workspace, imposta quello nuovo e attendi alcuni minuti. Un aggiornamento eseguito prima che la modifica raggiunga `auth.claude.com` può restituire token che vengono ancora eseguiti nel workspace precedente. Quindi, aggiorna ogni connessione che ha un refresh token e solo dopo archivia il workspace precedente. Se archivi prima un workspace, smetti di aggiornare le sue connessioni prima di impostarne un altro: un aggiornamento successivo termina la connessione.

  Non modificare né archiviare l’account di servizio operatore dell’app mentre un cliente è collegato. Dopo averlo modificato o archiviato, `auth.claude.com` rifiuta ogni aggiornamento e i token in tuo possesso smettono presto di addebitare i clienti. Ogni cliente di cui usi i token deve quindi collegarsi di nuovo: per assistenza, [contatta il supporto](https://support.claude.com/en/articles/9015913-how-to-get-support).
</Note>

### 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication).

### 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

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

<Note>
  Durante la beta, chiedi al tuo team di riferimento Anthropic se le richieste alla Claude API con il token di accesso di una connessione sono abilitate per la tua organizzazione. Finché non lo sono, ogni richiesta di questo tipo non va a buon fine, qualunque cosa invii. Chiedi inoltre se l’header `anthropic-user-profile-id` e `billing_policy` sono facoltativi. Finché non lo sono, invia ogni richiesta a `/v1/messages` e `/v1/chat/completions` che usa il token di accesso di una connessione come mostrato in [Paga il tuo cliente](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#your-customer-pays), con l’header, `bill_to: "user_profile"` e l’header beta di fatturazione.
</Note>

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` (typescript, php: `authToken`; java: `.authToken()`; csharp: `AuthToken`; go: `option.WithAuthToken()`), 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](https://platform.claude.com/docs/it/about-claude/pricing#code-execution-tool), 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](https://platform.claude.com/docs/it/build-with-claude/batch-processing).
* `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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#client-authentication) della tua app. Non inviare un parametro `scope`.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d @- <<JSON
  {
    "grant_type": "refresh_token",
    "refresh_token": "$CONNECTION_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "$CLIENT_ASSERTION"
  }
  JSON
  ```

  ```python Python
  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
  ```
</CodeGroup>

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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#oauth-token-snippet-initialization) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* `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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again), 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](https://code.claude.com/docs/it/agent-sdk/overview) 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](https://platform.claude.com/docs/it/manage-claude/wif-reference#profile-configuration-file)). 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.

```json 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:

```json 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.

```python
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](https://platform.claude.com/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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer). 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

<Note>
  Durante la beta, chiedi al tuo team di riferimento Anthropic se questa impostazione è disponibile per la tua organizzazione. Finché non lo è, non puoi attivarla.
</Note>

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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens). 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

```python
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](https://platform.claude.com/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](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api) 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](https://platform.claude.com/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](https://platform.claude.com/docs/it/manage-claude/admin-api#authentication), 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](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api#usage-endpoint) o il suo [endpoint dei costi](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api#cost-endpoint). 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](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api#data-freshness). [Tetti di spesa](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#spend-caps) indica cosa fanno i limiti propri del cliente.

### Scollegare un cliente

Per scollegare un cliente nella Console, usa l’elenco nella [pagina User profiles](https://platform.claude.com/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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#revocation), 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`.

<CodeGroup exclude="shell:CLI">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/revoke \
    -H "content-type: application/json" \
    -d @- <<'JSON'
  {
    "connection_id": "ocon_01HV9Z",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
  }
  JSON
  ```

  ```python Python
  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"]
  ```

  ```typescript TypeScript
  // Nessun SDK copre auth.claude.com, quindi questo esempio lo chiama direttamente.
  import { readFile } from "node:fs/promises";

  // L'ID della connessione che hai salvato nel Passaggio 8.
  const connectionId = "ocon_01HV9Z";

  // La client assertion: il JWT nel file del token di identità. Leggilo a ogni richiesta, perché il file viene ruotato.
  // Se l'autenticazione client della tua app prevede un audience diverso da quello del JWT, usa un secondo file di token.
  const clientAssertion = (
    await readFile(process.env.ANTHROPIC_IDENTITY_TOKEN_FILE!, "utf8")
  ).trim();

  const response = await fetch("https://auth.claude.com/v1/oauth/revoke", {
    method: "POST",
    redirect: "error",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      connection_id: connectionId,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: clientAssertion
    })
  });
  if (!response.ok) {
    throw new Error(`revoke failed: ${response.status}`);
  }

  const { revoked_connection_ids: revokedConnectionIds } = (await response.json()) as {
    revoked_connection_ids: string[];
  };
  console.log(revokedConnectionIds); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```csharp C#
  // Nessun SDK copre auth.claude.com, quindi questo esempio lo chiama direttamente.
  using System.Net.Http.Json;
  using System.Text.Json;

  // L'ID della connessione che hai salvato nel Passaggio 8.
  var connectionId = "ocon_01HV9Z";

  // La client assertion: il JWT nel file del token di identità. Leggilo a ogni richiesta, perché il file ruota.
  // Se l'autenticazione client della tua app si aspetta un audience diverso da quello del JWT, usa un secondo file di token.
  var tokenFile = Environment.GetEnvironmentVariable("ANTHROPIC_IDENTITY_TOKEN_FILE")!;
  var clientAssertion = (await File.ReadAllTextAsync(tokenFile)).Trim();

  using var http = new HttpClient();
  using var response = await http.PostAsJsonAsync(
      "https://auth.claude.com/v1/oauth/revoke",
      new Dictionary<string, string>
      {
          ["connection_id"] = connectionId,
          ["client_id"] = "YOUR_CLIENT_ID",
          ["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
          ["client_assertion"] = clientAssertion,
      }
  );
  response.EnsureSuccessStatusCode();

  var result = await response.Content.ReadFromJsonAsync<JsonElement>();
  Console.WriteLine(result.GetProperty("revoked_connection_ids")); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```go Go
  // Nessun SDK copre auth.claude.com, quindi questo esempio lo chiama direttamente.

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"os"
  	"strings"
  )

  func main() {
  	// L'ID della connessione che hai memorizzato nel Passaggio 8.
  	connectionID := "ocon_01HV9Z"

  	// La client assertion: il JWT nel file del token di identità. Leggilo a ogni richiesta, perché il file ruota.
  	// Se l'autenticazione client della tua app si aspetta un audience diverso da quello del JWT, usa un secondo file di token.
  	token, err := os.ReadFile(os.Getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))
  	if err != nil {
  		panic(err)
  	}

  	body, err := json.Marshal(map[string]string{
  		"connection_id":         connectionID,
  		"client_id":             "YOUR_CLIENT_ID",
  		"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  		"client_assertion":      strings.TrimSpace(string(token)),
  	})
  	if err != nil {
  		panic(err)
  	}

  	response, err := http.Post("https://auth.claude.com/v1/oauth/revoke", "application/json", bytes.NewReader(body))
  	if err != nil {
  		panic(err)
  	}
  	defer response.Body.Close()
  	if response.StatusCode < 200 || response.StatusCode > 299 {
  		panic(fmt.Sprintf("revoke failed: %d", response.StatusCode))
  	}

  	var result struct {
  		RevokedConnectionIDs []string `json:"revoked_connection_ids"`
  	}
  	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
  		panic(err)
  	}
  	fmt.Println(result.RevokedConnectionIDs) // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  }
  ```

  ```java Java
  // Nessun SDK copre auth.claude.com, quindi questo esempio lo chiama direttamente. L'SDK Java include Jackson.
  import com.fasterxml.jackson.databind.ObjectMapper;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.file.Files;
  import java.nio.file.Path;

  void main() throws Exception {
      // L'ID della connessione che hai memorizzato nel Passaggio 8.
      String connectionId = "ocon_01HV9Z";

      // La client assertion: il JWT nel file del token di identità. Leggilo a ogni richiesta, perché il file ruota.
      // Se l'autenticazione client della tua app prevede un audience diverso da quello del JWT, usa un secondo file di token.
      String clientAssertion = Files.readString(
          Path.of(System.getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))).strip();

      var mapper = new ObjectMapper();
      String body = mapper.createObjectNode()
          .put("connection_id", connectionId)
          .put("client_id", "YOUR_CLIENT_ID")
          .put("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
          .put("client_assertion", clientAssertion)
          .toString();

      var request = HttpRequest.newBuilder(URI.create("https://auth.claude.com/v1/oauth/revoke"))
          .header("content-type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(body))
          .build();
      var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() / 100 != 2) {
          throw new IllegalStateException("revoke failed: " + response.statusCode());
      }

      // ID delle connessioni terminate da questa richiesta. L'elenco è vuoto se la connessione era già terminata o l'ID è sconosciuto.
      IO.println(mapper.readTree(response.body()).get("revoked_connection_ids"));
  }
  ```

  ```php PHP
  // Nessun SDK copre auth.claude.com, quindi questo esempio lo chiama direttamente.

  // L'ID della connessione che hai memorizzato nel Passaggio 8.
  $connectionId = 'ocon_01HV9Z';

  // La client assertion: il JWT nel file del token di identità. Leggilo a ogni richiesta, perché il file viene ruotato.
  // Se l'autenticazione client della tua app si aspetta un'audience diversa da quella del JWT, usa un secondo file di token.
  $clientAssertion = trim(
      file_get_contents((string) getenv('ANTHROPIC_IDENTITY_TOKEN_FILE'))
          ?: throw new \RuntimeException('the file named by ANTHROPIC_IDENTITY_TOKEN_FILE cannot be read or is empty')
  );

  $body = json_encode([
      'connection_id' => $connectionId,
      'client_id' => 'YOUR_CLIENT_ID',
      'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
      'client_assertion' => $clientAssertion,
  ], JSON_THROW_ON_ERROR);

  $context = stream_context_create(['http' => [
      'method' => 'POST',
      'header' => 'content-type: application/json',
      'content' => $body,
  ]]);
  $response = file_get_contents('https://auth.claude.com/v1/oauth/revoke', context: $context);
  if ($response === false) {
      throw new \RuntimeException('revoke failed');
  }

  /** @var array{revoked_connection_ids: list<string>} $result */
  $result = json_decode($response, associative: true, flags: JSON_THROW_ON_ERROR);
  // ID delle connessioni terminate da questa richiesta. L'elenco è vuoto se la connessione era già terminata o l'ID è sconosciuto.
  echo implode(', ', $result['revoked_connection_ids']), PHP_EOL;
  ```

  ```ruby Ruby
  # Nessun SDK copre auth.claude.com, quindi questo esempio lo chiama direttamente.
  require "json"
  require "net/http"

  # L'ID della connessione che hai salvato nel Passaggio 8.
  connection_id = "ocon_01HV9Z"

  # L'asserzione del client: il JWT nel file del token di identità. Leggilo a ogni richiesta, perché il file ruota.
  # Se l'autenticazione client della tua app si aspetta un'audience diversa da quella del JWT, usa un secondo file di token.
  client_assertion = File.read(ENV.fetch("ANTHROPIC_IDENTITY_TOKEN_FILE")).strip

  response = Net::HTTP.post(
    URI("https://auth.claude.com/v1/oauth/revoke"),
    {
      connection_id: connection_id,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: client_assertion
    }.to_json,
    "content-type" => "application/json"
  )
  response.value # raises on an error

  # ID delle connessioni terminate da questa richiesta. L'elenco è vuoto se la connessione era già terminata o l'ID è sconosciuto.
  puts(JSON.parse(response.body).fetch("revoked_connection_ids"))
  ```
</CodeGroup>

`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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#revocation) per gli altri parametri ed [Errori dall’endpoint di revoca](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#errors-from-the-revocation-endpoint).

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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#after-connecting) descrive ciò che vede il tuo cliente, e [Email sul collegamento e lo scollegamento](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#emails-to-your-customer) 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](https://platform.claude.com/linked-platforms). Altrimenti, scollega il cliente, come descritto in [Scollegare un cliente](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer). Il profilo utente viene quindi mostrato come **Unlinked** nella tua pagina [User profiles](https://platform.claude.com/user-profiles).
2. Esegui di nuovo i [Passaggi da 5 a 8](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) con lo stesso profilo utente. Per il [Passaggio 7](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves), 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#spend-caps) 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`](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#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](https://platform.claude.com/docs/it/api/errors#sdk-error-types) per lo stato 403, che è `PermissionDeniedError` (java, php: `PermissionDeniedException`; csharp: `AnthropicForbiddenException`; go: `apierr.StatusCode == http.StatusForbidden`). 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#spend-caps) 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](https://platform.claude.com/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](https://platform.claude.com/settings/billing#spend-limits), può aumentarlo.
  * **Il saldo del credito:** nella propria pagina [Fatturazione](https://platform.claude.com/settings/billing), può vedere il proprio saldo del credito e acquistare credito. Alcuni crediti non possono pagare queste richieste: consulta [Quali crediti possono pagare](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#which-credits-can-pay).

* `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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token).

* `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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token).

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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) 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](https://platform.claude.com/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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).
* **L’organizzazione del cliente.** Deve essere un [cliente idoneo](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints). 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#spend-caps). Questa schermata è diversa mentre la tua app è in fase di test: consulta [Mentre la tua app è in fase di test](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing).
* **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](https://platform.claude.com/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`](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)). Il profilo utente del cliente viene mostrato come **Unlinked** nella tua pagina [User profiles](https://platform.claude.com/user-profiles) nella Console. Per ricollegarsi, esegui di nuovo i [Passaggi da 5 a 8](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#connecting)). È 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#expected-errors). 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](https://platform.claude.com/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](https://platform.claude.com/settings/billing#spend-limits). 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 approvata | Dopo che l’app è attiva  |
| --------------------------------------------------------- | --------------------------------------------- | ------------------------ |
| Un limite di spesa mensile nella pagina di approvazione   | Obbligatorio, $50 USD o meno                  | Facoltativo              |
| Il campo dell’importo nella pagina di approvazione        | Parte da $50 USD                              | Inizialmente vuoto       |
| **Continue without a limit** nella pagina di approvazione | Non disponibile                               | Disponibile              |
| Rimozione del tetto nella Console                         | Non possibile                                 | Possibile                |
| Il tetto massimo che un cliente può impostare             | $50 USD                                       | Nessun 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](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#spend-caps) 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`

```python
# 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()
```
