---
title: Riferimento OAuth
url: https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference
description: Endpoint, autenticazione del client, parametri di richiesta, scope, risposte dei token, revoca, durate, regole per i redirect URI ed errori.
---

<Warning>
  Claude Platform OAuth è un Beta Service: software in anteprima fornito in base al 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>

Questa pagina raccoglie gli endpoint, i parametri, le regole di validazione e le mappature degli errori per [Claude Platform OAuth](https://platform.claude.com/docs/it/manage-claude/oauth-apps/overview). Per una guida passo passo, consulta [Linked billing](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections).

## Endpoint

| Endpoint                                                                                   | URL                                                                            |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| Emittente                                                                                  | `https://identity.anthropic.com/users`                                         |
| Documento di discovery                                                                     | `https://identity.anthropic.com/users/.well-known/openid-configuration`        |
| Chiavi di firma (JWKS)                                                                     | Il `jwks_uri` nel documento di discovery, ospitato su `identity.anthropic.com` |
| Endpoint di autorizzazione (pagina di accesso e consenso)                                  | `https://auth.claude.com/oauth/authorize`                                      |
| Endpoint della “pushed authorization request” (richiesta di autorizzazione inviata), o PAR | `https://auth.claude.com/v1/oauth/par`                                         |
| Endpoint del token                                                                         | `https://auth.claude.com/v1/oauth/token`                                       |
| Endpoint di revoca                                                                         | `https://auth.claude.com/v1/oauth/revoke`                                      |
| Claude API (profili utente e richieste fatturate a un cliente)                             | `https://api.anthropic.com`                                                    |

Leggi le chiavi di firma dal documento di discovery invece di inserirle direttamente nel codice. Il documento di discovery non elenca l’endpoint PAR né l’endpoint di revoca, quindi usa gli URL indicati in questa tabella.

## Valori del documento di discovery

| Campo                                   | Valore                                           |
| --------------------------------------- | ------------------------------------------------ |
| `issuer`                                | `https://identity.anthropic.com/users`           |
| `authorization_endpoint`                | `https://auth.claude.com/oauth/authorize`        |
| `token_endpoint`                        | `https://auth.claude.com/v1/oauth/token`         |
| `jwks_uri`                              | `https://identity.anthropic.com/users/jwks.json` |
| `response_types_supported`              | `code`                                           |
| `grant_types_supported`                 | `authorization_code`, `refresh_token`            |
| `code_challenge_methods_supported`      | `S256`                                           |
| `token_endpoint_auth_methods_supported` | `private_key_jwt`                                |
| `id_token_signing_alg_values_supported` | `ES256`                                          |
| `scopes_supported`                      | `openid`, `email`                                |
| `subject_types_supported`               | `public`, `pairwise`                             |

`auth.claude.com` restituisce un “refresh token” (token di aggiornamento) per Linked billing solo quando il cliente ha approvato `offline_access` insieme a `billing:attribution`: consulta [Token OAuth per una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection).

## Autenticazione del client

`auth.claude.com` autentica un client confidenziale con il metodo `private_key_jwt` ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)). Invia questi parametri in ogni richiesta all’endpoint PAR, all’endpoint del token e all’endpoint di revoca. Non inviare mai le credenziali nella query string di un URL: `auth.claude.com` le rifiuta.

| Parametro               | Valore                                                                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client_id`             | L’ID client della tua app OAuth                                                                                                                                                                  |
| `client_assertion_type` | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`                                                                                                                                         |
| `client_assertion`      | Un JWT del tuo provider di identità con i claim indicati in [Claim della client assertion](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#client-assertion-claims) |

### Claim della client assertion

Una client assertion deve contenere tutti i seguenti claim, e il suo header deve contenere il `kid` di una chiave presente nel tuo JWKS.

| Claim | Requisito                                                                                                                                                                                          |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iss` | L’URL dell’issuer del tuo provider di identità, esattamente come registrato tramite [Workload Identity Federation](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation) |
| `sub` | Un valore che corrisponde al pattern del subject nelle impostazioni di autenticazione del client della tua app, se ne hai impostato uno                                                            |
| `aud` | Esattamente un’audience: il valore presente nelle impostazioni di autenticazione del client della tua app. `auth.claude.com` rifiuta un’assertion che elenca più di un’audience.                   |
| `iat` | Il momento in cui il tuo provider di identità ha emesso il JWT                                                                                                                                     |
| `exp` | L’ora di scadenza, non oltre 1 ora dopo `iat`. Usa una durata più breve quando puoi: chiunque intercetti un’assertion può usarla fino alla sua scadenza.                                           |

Esempio di payload dell’assertion:

```json
{
  "iss": "https://idp.example.com",
  "sub": "workload:prod:claude-integration-backend",
  "aud": "YOUR_CONFIGURED_AUDIENCE",
  "iat": 1791230000,
  "exp": 1791230300
}
```

Rendi il pattern del subject e le condizioni sui claim il più restrittivi possibile, compatibilmente con il tuo back end. `auth.claude.com` accetta come autenticazione per la tua app qualsiasi JWT del tuo provider di identità che vi corrisponda.

## Parametri della richiesta di autorizzazione

Invia questi parametri, tranne `request_uri`, nel corpo JSON di una pushed authorization request.

| Parametro                | Linked billing | Descrizione                                                                                                                                                                                                    |
| ------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type`          | Obbligatorio   | Il valore `code`                                                                                                                                                                                               |
| `client_id`              | Obbligatorio   | L’ID client della tua app OAuth                                                                                                                                                                                |
| `redirect_uri`           | Obbligatorio   | Un URI che corrisponde esattamente a un redirect URI registrato, fino a 2048 caratteri                                                                                                                         |
| `scope`                  | Obbligatorio   | Per una connessione di fatturazione, `billing:attribution` oppure `billing:attribution offline_access`. Consulta [Scope](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#scopes). |
| `state`                  | Obbligatorio   | Un valore casuale e monouso, fino a 2048 caratteri, che verifichi nel callback                                                                                                                                 |
| `code_challenge`         | Obbligatorio   | `BASE64URL(SHA256(code_verifier))`, dove il `code_verifier` è lungo da 43 a 128 caratteri                                                                                                                      |
| `code_challenge_method`  | Obbligatorio   | Il valore `S256`                                                                                                                                                                                               |
| `connection_type`        | Obbligatorio   | Il valore `organization_shared`. Con questo valore si richiede una connessione dell’organizzazione per la fatturazione.                                                                                        |
| `connection_auth_target` | Obbligatorio   | L’organizzazione verso cui vengono instradate le richieste della connessione. Per Linked billing, invia `platform` (il proprietario dell’app OAuth).                                                           |
| `user_profile_id`        | Obbligatorio   | L’ID di un profilo utente attivo nella tua organizzazione che rappresenta il cliente                                                                                                                           |
| `request_uri`            | Obbligatorio   | Il valore restituito dall’endpoint PAR. Invialo all’endpoint di autorizzazione con `client_id` e nessun altro parametro.                                                                                       |

L’endpoint PAR restituisce HTTP 201 con `request_uri` ed `expires_in` (600 secondi).

## Scope

| Categoria    | Scope                     | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                | Tipo di connessione   | Tipo di client |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | -------------- |
| Generale     | `offline_access`          | Fornisce all’app un token di aggiornamento che rappresenta gli altri scope richiesti. Su una connessione `organization_shared`, invialo solo insieme a `billing:attribution`.                                                                                                                                                                                                                                                              | `organization_shared` | Confidenziale  |
| Fatturazione | `billing:attribution`     | Una connessione che ti consente di addebitare all’organizzazione Claude di un cliente le richieste alla Claude API che il cliente ti chiede di effettuare. Invialo da solo oppure insieme a `offline_access` per ottenere anche un token di aggiornamento. Consulta [Token OAuth per una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). | `organization_shared` | Confidenziale  |
| Fatturazione | `org:billing_attribution` | Deprecato: usa `billing:attribution`.                                                                                                                                                                                                                                                                                                                                                                                                      | `organization_shared` | Confidenziale  |

## Richiesta e risposta del token

Invia le richieste del token a `https://auth.claude.com/v1/oauth/token` con un corpo JSON.

| Parametro                                                | Valore                                                                                                                                  |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `grant_type`                                             | `authorization_code`                                                                                                                    |
| `code`                                                   | Il codice ricevuto nel callback                                                                                                         |
| `redirect_uri`                                           | Lo stesso `redirect_uri` che hai inviato nella richiesta di autorizzazione                                                              |
| `code_verifier`                                          | Il code verifier PKCE                                                                                                                   |
| `client_id`, `client_assertion_type`, `client_assertion` | Come in [Autenticazione del client](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#client-authentication) |

La risposta del token contiene questi campi:

| Campo della risposta       | Linked billing                                                                                                                                              |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`             | [Il token di accesso della connessione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection) |
| `token_type`               | `Bearer`                                                                                                                                                    |
| `expires_in`               | Al massimo `3600`                                                                                                                                           |
| `scope`                    | `workspace:inference`                                                                                                                                       |
| `connection_id`            | L’ID della connessione, ad esempio `ocon_EXAMPLE`. Memorizzalo.                                                                                             |
| `refresh_token`            | Restituito solo quando il cliente ha approvato `offline_access`                                                                                             |
| `refresh_token_expires_in` | Secondi mancanti alla scadenza di `refresh_token`. Assente quando non c’è alcun `refresh_token`.                                                            |

Per effettuare l’aggiornamento, invia `grant_type` impostato su `refresh_token`, il tuo `refresh_token` e i parametri indicati in [Autenticazione del client](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#client-authentication). L’aggiornamento di una connessione di fatturazione segue le regole indicate in [Token OAuth per una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection).

## Token OAuth per una connessione di fatturazione

Per una connessione di fatturazione, l’endpoint del token restituisce il token di accesso della connessione. Il token si autentica come l’[account di servizio operatore](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#terms) della tua app, nel workspace indicato dall’impostazione `connection_token_workspace_id` dell’app. Su `/v1/messages` e `/v1/chat/completions`, una richiesta effettuata con questo token viene fatturata al cliente di quella connessione e a nessun altro. Quando il cliente ha approvato anche `offline_access`, l’endpoint del token restituisce anche un token di aggiornamento, e il grant `refresh_token` rinnova entrambi i token. Per la configurazione e la guida passo passo, consulta [Token OAuth per ciascuna connessione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) nella pagina Linked billing.

Entrambi i grant accettano i parametri indicati in [Richiesta e risposta del token](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#token-request-and-response), con [Autenticazione del client](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#client-authentication). Un aggiornamento non deve inviare un parametro `scope`. La risposta del token contiene questi campi:

| Campo della risposta       | Valore                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `access_token`             | Il token di accesso della connessione                                                                         |
| `token_type`               | `Bearer`                                                                                                      |
| `expires_in`               | Secondi mancanti alla scadenza del token di accesso, al massimo `3600`                                        |
| `scope`                    | Sempre `workspace:inference`                                                                                  |
| `connection_id`            | L’ID della connessione, ad esempio `ocon_EXAMPLE`. Lo restituisce solo il grant `authorization_code`.         |
| `refresh_token`            | Il token di aggiornamento della connessione. Restituito solo quando il cliente ha approvato `offline_access`. |
| `refresh_token_expires_in` | Secondi mancanti alla scadenza di `refresh_token`                                                             |

Ogni aggiornamento restituisce un nuovo `access_token` e un nuovo `refresh_token`. Il token di aggiornamento che hai inviato viene sostituito, e il token di accesso precedente smette di funzionare entro pochi minuti. Puoi inviare il token di aggiornamento sostituito ancora una volta, entro 30 secondi dall’aggiornamento che lo ha sostituito, per ripetere una richiesta di cui hai perso la risposta. Questa seconda richiesta restituisce un’altra nuova coppia e revoca la coppia della risposta persa: usa solo la coppia più recente. Una terza richiesta con il token sostituito riceve `invalid_grant`, così come una seconda richiesta che arriva dopo i 30 secondi. Entro i 30 secondi, una richiesta di questo tipo non revoca nulla. Dopo i 30 secondi, revoca tutti i token della connessione e termina la connessione. La sezione [Aggiorna i token](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) riporta le regole e gli errori di un aggiornamento.

Ciascuno di questi eventi revoca i token della connessione, compreso il token di accesso corrente:

* Il cliente o tu annullate il collegamento.
* Il cliente approva una nuova richiesta di autorizzazione con scope diversi per lo stesso profilo utente e tu scambi il codice di quell’approvazione. La nuova connessione prende il posto di quella precedente.
* Il workspace in cui operano i token viene archiviato.

Per sapere come la Claude API fattura una richiesta effettuata con il token di accesso di una connessione, 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).

## Revoca

Invia le richieste di revoca a `https://auth.claude.com/v1/oauth/revoke` con un corpo JSON o codificato come form. L’endpoint segue [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) e accetta anche ID di connessione e di profilo utente.

Invia i parametri indicati in [Autenticazione del client](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#client-authentication) ed esattamente uno dei parametri di questa tabella. L’`aud` della client assertion è il valore presente nelle impostazioni di autenticazione del client della tua app, non l’URL di revoca.

| Parametro         | Cosa termina                                                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_id`   | Una delle connessioni della tua app, indicata come ID `ocon_`                                                                               |
| `user_profile_id` | Tutte le connessioni della tua app su un profilo utente, indicato come ID `uprof_`                                                          |
| `token`           | Per Linked billing, invia invece `connection_id` o `user_profile_id`: l’invio di un token di accesso potrebbe non terminare la connessione. |

`auth.claude.com` accetta `token_type_hint` e lo ignora.

L’endpoint restituisce HTTP 200 e gli ID delle connessioni che la richiesta ha terminato:

```json
{
  "revoked_connection_ids": ["ocon_EXAMPLE"]
}
```

L’elenco è vuoto se il token o l’ID è sconosciuto o appartiene a un’altra app, se la connessione è già terminata oppure se la richiesta ha terminato un token ma nessuna connessione. La risposta non indica di quale caso si tratta.

Dopo la fine di una connessione di fatturazione, la Claude API rifiuta le richieste fatturate a quel cliente con `user_profile_not_billable`, e i token OAuth della connessione smettono di funzionare. Da quel momento non fare affidamento su un token di accesso di una connessione approvata con lo scope deprecato `org:billing_attribution`: potrebbe smettere di funzionare subito oppure funzionare fino alla scadenza.

## Durate

| Elemento                        | Durata                                                                              |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| `request_uri` dall’endpoint PAR | 10 minuti, monouso                                                                  |
| Codice di autorizzazione        | 5 minuti, monouso                                                                   |
| `access_token`                  | Fino a 1 ora                                                                        |
| `refresh_token`                 | Fino a 1 anno dallo scambio del codice. Un aggiornamento non ne prolunga la durata. |

Questi sono i valori attuali. Leggi `expires_in` e `refresh_token_expires_in` da ogni risposta invece di fare affidamento su valori fissi.

## Regole per i redirect URI

* Ogni `redirect_uri` deve corrispondere esattamente a un URI registrato sulla tua app. `auth.claude.com` non usa corrispondenze con caratteri jolly o per prefisso.
* Ogni redirect URI deve usare HTTPS e non deve contenere un frammento. Gli URI di sviluppo locale su `localhost`, `127.0.0.1` o `[::1]` possono usare HTTP.
* Un URI di sviluppo locale registrato con un asterisco come porta, ad esempio `http://localhost:*/callback`, corrisponde a qualsiasi porta.
* Puoi registrare fino a 10 redirect URI per ogni app.
* `auth.claude.com` invia gli errori al tuo redirect URI solo quando il `redirect_uri` corrisponde a un URI registrato. Per qualsiasi altro `redirect_uri`, `auth.claude.com` non reindirizza il browser.

## Errori

### Errori sul redirect

`auth.claude.com` restituisce gli errori come parametri di query `error`, `error_description` e `state` sul tuo redirect URI. Si tratta di errori standard di OAuth 2.0 ([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749)), tranne `user_profile_already_linked`, che è specifico di Anthropic.

| Errore                        | Quando                                                                                                                                                                                                                                                         | Cosa mostrare all’utente                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_denied`               | La persona ha rifiutato, oppure non può approvare questa richiesta. Per una connessione di fatturazione, la persona deve essere un amministratore di un’organizzazione Claude.                                                                                 | Spiega che la connessione non è stata completata e non dare per scontato che la persona abbia rifiutato. Per una connessione di fatturazione, segui [Il tuo redirect URI riceve `error=access_denied`](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#access-denied) nella guida Linked billing, che elenca le cause e cosa dire alla persona. Altrimenti, chiedi alla persona di contattarti. |
| `server_error`                | `auth.claude.com` non è riuscito a elaborare la richiesta.                                                                                                                                                                                                     | Chiedi all’utente di riprovare.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `user_profile_already_linked` | Solo Linked billing. L’organizzazione del cliente è già collegata alla tua app tramite un profilo utente diverso. Ogni organizzazione cliente può avere una sola connessione alla tua app. `auth.claude.com` ha già chiesto all’amministratore di contattarti. | Spiega che la sua organizzazione è già collegata alla tua app.                                                                                                                                                                                                                                                                                                                                                                                |

Se il `request_uri` è scaduto oppure l’hai già usato, `auth.claude.com` mostra una pagina di errore e non reindirizza il browser alla tua app. Ricomincia il flusso con una nuova pushed authorization request.

### Errori dagli endpoint PAR e del token

Questi endpoint restituiscono un corpo JSON con `error` ed `error_description`.

| Errore                        | Quando                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`             | Un parametro obbligatorio è mancante o non valido, ad esempio manca `state` o la challenge PKCE, oppure un `user_profile_id` non è l’ID di un profilo utente attivo nella tua organizzazione.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `invalid_client`              | `auth.claude.com` non è riuscito ad autenticare la tua app: l’ID client è sconosciuto oppure la verifica della client assertion non è riuscita. Confronta `iss`, `sub` e `aud` dell’assertion con le impostazioni di autenticazione del client della tua app, e verifica che il tuo provider di identità l’abbia firmata con una chiave presente nel tuo JWKS.                                                                                                                                                                                                                                                                                                                          |
| `invalid_scope`               | Lo scope richiesto non è consentito per questa app o per questo tipo di connessione. Per i [token di una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection), significa anche che un aggiornamento ha inviato un parametro `scope`, che non accetta, oppure che `billing:attribution` non è più registrato per la tua app. Durante lo scambio del codice, questa seconda causa consuma il codice.                                                                                                                                                                                          |
| `invalid_grant`               | Il codice è scaduto, l’hai già usato oppure non corrisponde a `redirect_uri` o `code_verifier`. Per un aggiornamento, il token di aggiornamento è scaduto o non è più valido: segui [Aggiorna i token](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection).                                                                                                                                                                                                                                                                                                                                                           |
| `unauthorized_client`         | La tua app non è configurata per questa richiesta. Per Linked billing, verifica prima l’account di servizio operatore dell’app e il suo workspace: 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). Per i [token di una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection), `error_description` indica la causa, ad esempio un workspace mancante. Questo rifiuto non consuma alcun codice e non revoca alcun token di aggiornamento. |
| `user_profile_already_linked` | Solo Linked billing, dall’endpoint del token. Tra l’approvazione e questa richiesta, il profilo utente è stato collegato alla tua app tramite un’organizzazione cliente diversa, oppure l’organizzazione del cliente è stata collegata tramite un profilo utente diverso.                                                                                                                                                                                                                                                                                                                                                                                                               |

Se `auth.claude.com` applica un “rate limit” (limite di velocità) a una richiesta, subisce un’interruzione del servizio oppure riceve un `grant_type` sconosciuto o un parametro più lungo del suo limite, restituisce un errore in un formato diverso, che potrebbe non essere JSON. Riprova solo in caso di risposte HTTP 429 e 5xx, con backoff. Considera qualsiasi altro stato come un errore nella richiesta. Per l’aggiornamento di una connessione di fatturazione, segui [Aggiorna i token](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) invece di un backoff generico. Se la risposta contiene un header `retry-after`, attendi almeno quel tempo. Invia la richiesta successiva dal tuo codice e non fare affidamento sui tentativi automatici di una libreria client HTTP: potrebbero non essere eseguiti per una risposta di questo tipo. [Aggiorna i token](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection) indica anche quando è sicuro riprovare, perché un token di aggiornamento già usato può terminare la connessione quando lo invii di nuovo.

### Errori dall’endpoint di revoca

Per la maggior parte delle richieste che `auth.claude.com` rifiuta, l’endpoint di revoca restituisce HTTP 400 e un corpo JSON con `error` ed `error_description`.

| Errore                | Quando                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`     | Un parametro obbligatorio è mancante o non valido, ad esempio manca `client_id`. La richiesta non invia nessuno tra `token`, `connection_id` e `user_profile_id`, oppure ne invia più di uno. Un ID non è formattato correttamente, ad esempio ha il prefisso sbagliato. Una credenziale o un `token` si trova nella query string dell’URL. Il profilo utente ha troppe connessioni per una sola richiesta: la richiesta potrebbe averne terminate alcune, quindi termina le restanti con `connection_id`. |
| `invalid_client`      | `auth.claude.com` non è riuscito ad autenticare la tua app. Per sapere cosa verificare, consulta `invalid_client` in [Errori dagli endpoint PAR e del token](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#errors-from-the-par-and-token-endpoints).                                                                                                                                                                                                                        |
| `unauthorized_client` | La tua app non è configurata per questa richiesta. Contatta il tuo team di riferimento Anthropic.                                                                                                                                                                                                                                                                                                                                                                                                          |

Le risposte nella tabella seguente usano un formato diverso, che potrebbe non essere JSON. Quando il corpo è JSON, `error` è un oggetto, non una stringa.

| Stato | Quando                                                                     | Cosa fare                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400   | Un parametro è più lungo del suo limite.                                   | Correggi la richiesta. Non riprovare.                                                                                                                                                                                                                                                                                                                                                                                                            |
| 429   | Sono arrivate troppe richieste non riuscite dal tuo indirizzo IP.          | Riprova con backoff.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 500   | `auth.claude.com` non è riuscito a elaborare la richiesta.                 | Riprova con backoff. Se il problema persiste, contatta il tuo team di riferimento Anthropic.                                                                                                                                                                                                                                                                                                                                                     |
| 501   | Anthropic non ha abilitato questo endpoint per la tua organizzazione.      | Non riprovare. Contatta il tuo team di riferimento Anthropic.                                                                                                                                                                                                                                                                                                                                                                                    |
| 503   | La richiesta non è stata completata. Ciò che ha terminato resta terminato. | Riprova con backoff, con gli stessi parametri e una nuova client assertion. Il nuovo tentativo completa il resto, e il suo elenco esclude le connessioni che la richiesta precedente ha terminato. Se hai inviato `user_profile_id`, riprova entro un giorno: dopo tale periodo, un nuovo tentativo può restituire 200 con un elenco vuoto e non completare nulla. Un nuovo tentativo con ciascun `connection_id` funziona in qualsiasi momento. |

### Errori di fatturazione

Si applicano alle richieste alla Claude API che impostano `billing_policy.bill_to` su `"user_profile"` oppure che si autenticano con [il token di accesso di una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). La Claude API non addebita una richiesta rifiutata a nessuna delle due organizzazioni. Nessuna delle risposte 402 e 403 è ripetibile, tranne un rifiuto `user_profile_not_billable` nei primi 10 secondi dopo una nuova connessione.

| Stato | Tipo e codice di errore                                    | Quando                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400   | `invalid_request_error`                                    | La richiesta invia `billing_policy` senza l’header beta `user-profiles-billing-2026-10-01`. Oppure l’oggetto `billing_policy` ha un campo mancante o non valido. Con il token di accesso di una connessione di fatturazione, `bill_to` può essere omesso. Oppure la richiesta usa l’esecuzione del codice al di fuori della combinazione consentita.                                                                                                                                                                                                                                                                                                                                                                                           |
| 400   | `invalid_request_error`, `user_profile_required`           | `bill_to` è `"user_profile"`, la richiesta non include un ID di profilo utente e non si autentica con il token di accesso di una connessione di fatturazione.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 400   | `invalid_request_error`, senza codice di errore            | La richiesta si autentica con il token di accesso di una connessione di fatturazione e imposta `bill_to` su `"self"` oppure indica un profilo utente diverso da quello a cui il token è limitato. Ciascuno di questi due rifiuti indica il problema in `error.message`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 401   | `authentication_error`                                     | La richiesta si autentica con il token di accesso di una connessione di fatturazione che è scaduto, che un aggiornamento ha sostituito o la cui connessione è terminata. Il messaggio indica se il token è scaduto o è stato revocato. Invia di nuovo la richiesta con il token di accesso corrente, oppure collega di nuovo il cliente se la connessione è terminata. Dopo la fine di una connessione, ogni nuova richiesta con il suo token di accesso può ricevere questo 401 o un 403 `user_profile_not_billable`, senza un ordine fisso.                                                                                                                                                                                                  |
| 402   | `billing_error`, `linked_organization_spend_limit_reached` | L’organizzazione cliente ha raggiunto un limite di spesa da essa impostato, per la tua app OAuth o 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 di quale caso si tratta. Chiedi al cliente di verificare entrambi i limiti e il proprio saldo di credito. La sezione [Errori previsti](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#expected-errors) per Linked billing indica dove viene impostato ciascuno e cosa modificare.                                                                                                                                       |
| 402   | `billing_error`, `linked_organization_billing_unavailable` | Al momento Anthropic non può fatturare l’organizzazione cliente a causa di un problema con l’account Anthropic proprio di quell’organizzazione. Lo stesso codice interrompe una risposta che Claude ha già iniziato quando il credito dell’organizzazione si esaurisce. Chiedi al cliente di verificare il proprio stato di fatturazione con Anthropic.                                                                                                                                                                                                                                                                                                                                                                                        |
| 403   | `permission_error`, senza codice di errore                 | Anthropic non fattura direttamente la tua organizzazione, quindi non può fatturare i clienti per tuo conto.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 403   | `permission_error`, `user_profile_not_billable`            | Il profilo utente non ha alcuna connessione a un’organizzazione cliente, un amministratore o il tuo back end ha terminato la connessione, l’organizzazione cliente non paga Anthropic direttamente per il proprio utilizzo dell’API (valgono sia i crediti prepagati sia il pagamento su fattura), oppure la richiesta non si autentica come account di servizio della tua app. La risposta non indica di quale caso si tratta. Anche il token di accesso di una connessione può riceverlo dopo la fine della connessione. La sezione [Cause di `user_profile_not_billable`](https://platform.claude.com/docs/it/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable) indica cosa verificare per ciascun caso. |
| 503   | `overloaded_error`                                         | La Claude API temporaneamente non riesce a confermare se può fatturare il cliente. Riprova la richiesta. Se la risposta include un header `retry-after`, attendi quel tempo prima di riprovare.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

Su `/v1/messages`, il codice di errore si trova in `error.details.error_code`. Su `/v1/chat/completions`, `error.type` è sempre `invalid_request_error`, `error.code` contiene il tipo di errore Anthropic (ad esempio `permission_error` o `billing_error`) e la risposta non contiene alcun codice di errore, quindi basati sullo stato HTTP e su `error.code`.

## Standard

| Standard                                                                           | Dove si applica                                                                                                                                                                       |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [OAuth 2.0 (RFC 6749)](https://www.rfc-editor.org/rfc/rfc6749)                     | Flusso del codice di autorizzazione, endpoint del token e risposte di errore                                                                                                          |
| [PKCE (RFC 7636)](https://www.rfc-editor.org/rfc/rfc7636)                          | Obbligatorio con `S256` in ogni richiesta di autorizzazione                                                                                                                           |
| [Pushed authorization requests (RFC 9126)](https://www.rfc-editor.org/rfc/rfc9126) | Obbligatorio per Linked billing.                                                                                                                                                      |
| [Revoca dei token (RFC 7009)](https://www.rfc-editor.org/rfc/rfc7009)              | L’endpoint di revoca, che accetta anche ID di connessione e di profilo utente e restituisce gli ID delle connessioni che ha terminato                                                 |
| [Autenticazione del client JWT (RFC 7523)](https://www.rfc-editor.org/rfc/rfc7523) | L’autenticazione del client `private_key_jwt` presso gli endpoint PAR, del token e di revoca, e lo scambio del token dell’account di servizio per le richieste fatturate a un cliente |

## Termini usati in queste pagine

I seguenti significati si applicano solo a Claude Platform OAuth.

| Termine                            | Significato                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organizzazione Claude              | Un account di organizzazione presso Anthropic. La tua azienda ne ha uno, così come ogni cliente che collega la propria organizzazione per la fatturazione.                                                                                                                                                                                                                                                                                                                                                       |
| Amministratore                     | Un membro di un’organizzazione Claude con il ruolo Amministratore o Fatturazione.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| App OAuth                          | La registrazione nella tua organizzazione Claude che identifica il tuo prodotto presso `auth.claude.com`. Ha un ID client, un nome, un logo, un URL della homepage, redirect URI e i tipi di connessione che supporta.                                                                                                                                                                                                                                                                                           |
| Tipo di connessione                | Chi approva una connessione: un amministratore per conto di un’intera organizzazione (`organization_shared`, per Linked billing).                                                                                                                                                                                                                                                                                                                                                                                |
| Provider di identità               | Il servizio nella tua infrastruttura che firma JWT di breve durata per il tuo back end e pubblica le sue chiavi pubbliche come JSON Web Key Set (JWKS), ad esempio il servizio di identità dei carichi di lavoro del tuo provider cloud o un tuo issuer conforme a OIDC. In queste pagine, “il tuo provider di identità” indica sempre questo servizio, non Anthropic.                                                                                                                                           |
| Client assertion                   | Un JWT di breve durata che il tuo provider di identità firma e che il tuo back end invia per autenticare la tua app OAuth. Si tratta del metodo di autenticazione del client `private_key_jwt` (RFC 7523).                                                                                                                                                                                                                                                                                                       |
| Pushed authorization request (PAR) | Una richiesta in cui il tuo back end invia i parametri di autorizzazione direttamente a `auth.claude.com` e riceve un `request_uri` da usare nel redirect del browser (RFC 9126).                                                                                                                                                                                                                                                                                                                                |
| Workload Identity Federation       | La funzionalità della Claude Console tramite la quale la tua organizzazione registra il tuo provider di identità, in modo che Anthropic accetti i JWT firmati con le chiavi presenti nel tuo JWKS.                                                                                                                                                                                                                                                                                                               |
| Documento di discovery             | Il documento OIDC che elenca l’issuer, gli endpoint e le chiavi di firma di Anthropic.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Profilo utente                     | Un record che crei nella tua organizzazione Claude per rappresentare uno dei tuoi clienti. Una connessione di fatturazione collega un profilo utente all’organizzazione Claude del cliente.                                                                                                                                                                                                                                                                                                                      |
| Account di servizio                | Un account non umano nella tua organizzazione Claude. Per Linked billing, la tua app OAuth è collegata a un account di servizio, il suo account di servizio operatore, e il tuo back end si autentica come tale account di servizio quando invia una richiesta fatturata a un cliente.                                                                                                                                                                                                                           |
| Token OAuth della connessione      | Il token di accesso che `auth.claude.com` restituisce per una connessione di fatturazione e il token di aggiornamento che restituisce quando il cliente ha approvato anche `offline_access`. Il token di accesso si autentica come l’account di servizio operatore e può fatturare solo il profilo utente di quella connessione. Consulta [Token OAuth per una connessione di fatturazione](https://platform.claude.com/docs/it/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection). |
