> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creditbenchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Richieda un token di accesso

> Firmare un’asserzione client ES256 e scambiarla con un token di accesso bearer a breve durata utilizzando il flusso di asserzione client bearer JWT di OAuth 2.0.

L’autenticazione utilizza il flusso **di asserzione client JWT bearer** OAuth 2.0 ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)) con un grant `client_credentials`. Il segreto del cliente non viene mai trasmesso.

È necessario:

* Il Suo **`OAuthClientId`** e il Suo **`KID`**, riportati nel Suo pacchetto di onboarding.
* La **chiave privata** (`es256-private.pem`) corrispondente alla chiave pubblica da Lei registrata. Veda [Configurazione della coppia di chiavi](/api-reference/authentication/key-pair-setup).

## Fase 1: Creazione dell’asserzione del client

Creare un JWT e firmarlo con la propria chiave **privata** ES256.

**Intestazione**

```json theme={null}
{ "alg": "ES256", "typ": "JWT", "kid": "<KID>" }
```

**Payload**

```json theme={null}
{
  "iss": "<OAuthClientId>",
  "sub": "<OAuthClientId>",
  "aud": "cb-gateway-m2m-blue",
  "jti": "<random UUID>",
  "iat": 1790812800,
  "exp": 1790812920
}
```

| Richiesta | Valore |
| - | - |
| `iss`, `sub` | Entrambe **devono** corrispondere al Suo `OAuthClientId`. |
| `aud` | **Deve** corrispondere esattamente `cb-gateway-m2m-blue`. Non si tratta dell’URL del gateway. |
| `jti` | Un nuovo UUID casuale per ogni asserzione. Le asserzioni sono monouso. |
| `iat` | L’ora corrente, espressa in secondi Unix. |
| `exp` | `iat` più 120 secondi. Le asserzioni sono progettate per avere una durata limitata. |

## Fase 2: Scambio con un token di accesso

`POST` l’asserzione all’endpoint del token come `application/x-www-form-urlencoded`. Si veda l’[Riferimento all’endpoint](/api-reference/create-jwt-token) per lo schema completo.

```http theme={null}
POST /api/security/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<signed JWT>
&OAuthClientId=<OAuthClientId>
```

La risposta è in formato JSON e contiene un `accessToken` campo, valido per 30 minuti (`expiresIn: 1800`). Ai clienti M2M non viene emesso alcun token di aggiornamento, pertanto `refreshToken` è sempre `null`.

## Fase 3: Richiamare l’API

Inviare il token come token di tipo Bearer in ogni richiesta:

| Intestazione | Valore |
| - | - |
| `Authorization` | `Bearer <accessToken>` |
| `Content-Type` | `application/json` |
| `Accept` | `application/json` |

Richieda un nuovo token alla scadenza, anziché conservarlo nella cache a lungo termine.

## Esempio completo

Consulti il sito [Script di esempio](/api-reference/authentication/sample-scripts) per le versioni eseguibili in TypeScript e Python dell’intero flusso. Il Suo pacchetto di onboarding include gli stessi script con i Suoi dati già inseriti.

## Risoluzione dei problemi

### Errore 401 dall’endpoint del token

L’endpoint del token restituisce lo stesso messaggio vuoto `401` per ogni asserzione rifiutata. Verificare ciascuno dei seguenti punti:

* L’intestazione `alg` è `ES256` e `kid` è quella `KID` di una chiave registrata e non revocata.
* `iss` corrisponde esattamente alla Sua `OAuthClientId`. Ricerchiamo la Sua chiave pubblica tramite `iss` e `kid`.
* `aud` è esattamente `cb-gateway-m2m-blue`.
* `exp` sia presente e in futuro. Consentiamo uno scostamento dell’orologio di 30 secondi; pertanto, verifichi l’orologio del computer qualora gli errori persistano.
* `jti` sia presente e nuova. Un `jti` non può essere riutilizzato entro 10 minuti.
* L’asserzione è firmata con la chiave privata corrispondente alla chiave pubblica da Lei registrata.

### 401 "Accesso non autorizzato" dai percorsi API

Il token di accesso è scaduto (i token hanno una durata di 30 minuti) oppure il percorso non rientra nei Suoi diritti di accesso. Richieda un nuovo token e, se l’errore persiste, contatti il Suo amministratore di Credit Benchmark.

### Una chiave è mancante, revocata o sottoposta a rotazione

Si rivolga al Suo amministratore di Credit Benchmark.

## Nota sulla sicurezza

* **Non** condivida **mai** la Sua chiave privata con nessuno, compreso Credit Benchmark. Solo la chiave pubblica deve uscire dai Suoi sistemi.
* Generare una nuova asserzione client per ogni richiesta di token.
* Qualora una chiave privata dovesse mai essere compromessa, ci chieda di revocarla immediatamente e segua la procedura descritta all’indirizzo [Rotazione delle chiavi](/api-reference/authentication/key-pair-setup#key-rotation).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.