# API

Protegga le Sue API come risorse OAuth: definisca gli scope, controlli l'accesso machine-to-machine e utente, imposti formato e durata dei token.

Un'**API** rappresenta una risorsa protetta per la quale le applicazioni ottengono access token. La registrazione di un'API comunica alla piattaforma l'identificatore della risorsa (la sua audience), gli **scope** (autorizzazioni) che espone, quali applicazioni possono chiamarla e come vengono strutturati e firmati gli access token emessi per essa.

Le API si gestiscono nell'Admin Console in **Integrazioni → API**.

## Che cos'è un'API

Ogni API dispone di:

- un **nome**: un'etichetta per gli amministratori, e
- un **identificatore**: il valore di audience che compare nei token emessi per questa API (ad esempio `https://api.example.com`).

Per un'API personalizzata può inoltre indicare dei **contatti**, ovvero i dipendenti a cui rivolgersi in merito. Hanno solo valore informativo e non ricevono alcun diritto.

Esistono due tipi:

- **System API**: l'API di gestione della piattaforma stessa. Nome, identificatore e scope sono fissi e non possono essere modificati.
- **Custom API**: un'API che Lei registra e governa: ne definisce gli scope, chi può chiamarla e le impostazioni dei token.

## Scope (autorizzazioni)

Uno scope è una singola autorizzazione che un token può contenere, ad esempio `read:documents` oppure `orders.write`.

- La **System API** espone un catalogo fisso di scope di gestione (ad esempio `users.read`, `users.write`, `groups.read`, `roles.write`, `logs.read`). Sono gli scope che Lei concede alle applicazioni che chiamano l'API di gestione della piattaforma.
- Una **Custom API** espone gli scope definiti da *Lei*. Nella scheda delle autorizzazioni dell'API, aggiunga ogni scope con un nome e una descrizione. Alcuni scope OpenID Connect riservati (come `openid`, `profile`, `email`, `offline_access`) non possono essere ridefiniti.

Alcuni scope di gestione si affiancano deliberatamente al proprio scope di base invece di esserne inclusi. Quello da conoscere è `users.mfa.read`, che copre le registrazioni MFA di un utente (quali secondi fattori sono registrati e quando ciascuno è stato utilizzato l'ultima volta). È richiesto su **ogni** endpoint che restituisce un utente, comprese le risposte delle chiamate di creazione, aggiornamento, eliminazione, disattivazione e attivazione. Un token che contiene solo `users.read` o `users.write` riceve l'utente senza l'elenco delle registrazioni, quindi conceda anche `users.mfa.read` quando un'integrazione ne ha bisogno.

## Chi può chiamare un'API

Due policy indipendenti controllano l'accesso, una per ciascun tipo di chiamante:

### Accesso delegato dall'utente [#user-delegated-access]

Quando un'applicazione interattiva richiede un token *per conto di un utente che ha effettuato l'accesso*, la **user policy** dell'API decide se è consentito:

- **Allow all**: qualsiasi applicazione interattiva può richiedere token per questa API.
- **Require grant**: solo le applicazioni a cui Lei ha concesso esplicitamente l'accesso possono richiedere token, e solo per gli scope che ha concesso loro.
- **Deny all**: nessuna applicazione interattiva può richiedere token.

### Accesso machine-to-machine

Quando un'applicazione si autentica *per conto proprio* con il grant client credentials (senza alcun utente coinvolto), la **client policy** dell'API decide se è consentito:

- **Require grant**: solo le applicazioni a cui Lei ha concesso esplicitamente l'accesso possono richiedere token, limitatamente agli scope concessi.
- **Deny all**: nessuna applicazione machine-to-machine può richiedere token.

### Concedere l'accesso a un'applicazione [#granting-an-application]

Quando una policy è impostata su **require grant**, autorizzi un'applicazione dalla scheda **Accesso all'applicazione** dell'API:

1. Scelga **Aggiungi applicazione** nella sezione delegata dall'utente o nella sezione client (machine-to-machine).
2. Selezioni l'applicazione.
3. Selezioni gli scope da concedere, oppure scelga **Concedi sempre tutte le autorizzazioni** per includere automaticamente gli scope attuali e futuri.
4. Salvi. I token che la piattaforma emette a quell'applicazione per questa API contengono ora gli scope concessi.

Un'applicazione machine-to-machine è in genere del tipo di applicazione *machine-to-machine*, vedere [Applicazioni](https://dts-identity.com/it/docs/integrations/applications.md).

[Image: L'elenco delle API nell'Admin Console]

## Testare un token API

Quando per un'API è autorizzata almeno un'applicazione machine-to-machine (con il grant client credentials), la scheda **Test** dell'API Le consente di provare un token dall'inizio alla fine senza scrivere codice:

1. Selezioni una delle applicazioni machine-to-machine autorizzate.
2. La pagina mostra un esempio di **token request** pronto all'uso verso il token endpoint, con il client ID e il secret di quell'applicazione e l'identificatore di questa API come audience.
3. Mostra la **token response** e decodifica l'access token emesso nei suoi **header**, **payload** e **firma**, così può verificare che audience e scope concessi siano quelli attesi.
4. Mostra un esempio di **chiamata API** che invia il token come header `Bearer`.

Copi i comandi per eseguirli nel Suo terminale. Se la scheda Test Le chiede di autorizzare prima un'applicazione, conceda l'accesso a un'applicazione machine-to-machine nella scheda **Accesso all'applicazione** e ricarichi la pagina.

## Resource indicator e token [#resource-indicators-and-tokens]

Ogni access token che la piattaforma emette per un'API contiene l'identificatore di quell'API come **audience**, così la risorsa può verificare che il token fosse destinato a lei. Le applicazioni scelgono l'API per cui desiderano un token tramite il resource indicator, il che consente a un'applicazione di detenere token separati, ciascuno con la propria audience, per più API.

Nella scheda delle impostazioni dell'API Lei controlla come sono strutturati questi token:

- **Algoritmo di firma**: l'algoritmo asimmetrico (RS256, RS384, RS512 o PS256) utilizzato per firmare i token. Scelga **PS256** per un'API chiamata da un'applicazione che utilizza un [profilo di sicurezza Financial-grade API](https://dts-identity.com/it/docs/integrations/applications.md#financial-grade-api-security): tale profilo firma i token dell'applicazione stessa con PS256 e sconsiglia RS256. Questa impostazione è indipendente dal profilo, quindi deve essere modificata anche qui.
- **Access token lifetime**: per quanto tempo un token è valido (il valore predefinito è un giorno).
- **Implicit access token lifetime**: una durata più breve applicata ai token emessi tramite i flussi implicit basati su browser (il valore predefinito è due ore).

## Una API o più API? [#one-api-or-many]

Un access token contiene sempre esattamente **una audience**. I token con più audience non vengono emessi: un token emesso per un'API non viene accettato da un'altra (vedere [L'API come contratto verificabile](#the-api-as-a-verifiable-contract)). Se il Suo backend è un insieme di microservizi, ne deriva una scelta di progettazione:

**Una API logica per un dominio di fiducia.** Registri una singola API il cui identificatore rappresenta l'intero backend (ad esempio `https://api.example.com`) e assegni a ogni servizio un proprio namespace di scope (`orders.read`, `inventory.write` e così via). Ogni servizio convalida la stessa audience e applica solo i propri scope; il client detiene un unico token per l'intero backend e un nuovo servizio si aggiunge con nuovi scope anziché con una nuova registrazione. Scelga questa opzione quando i servizi vengono sviluppati e gestiti insieme, tipicamente dietro un unico gateway. Tenga presente il compromesso: all'interno dell'audience condivisa i servizi non si isolano più a vicenda tramite il controllo dell'audience (ciascuno accetta un token inviato a un servizio fratello), ma solo tramite gli scope.

**Una API per ogni confine di fiducia.** Registri API separate quando le risorse hanno livelli di fiducia o proprietari diversi, oppure quando sono coinvolte terze parti. Un client richiede allora un token separato per ogni API tramite il resource indicator (vedere [Resource indicator e token](#resource-indicators-and-tokens)), e un servizio backend può scambiare un token già in suo possesso tramite il [token exchange](#token-exchange). Oltre il confine, il controllo dell'audience mantiene il suo significato: un token intercettato presso un'API non ha alcun valore presso l'altra.

Combinare entrambi gli approcci è comune: una API logica per il nucleo coeso, API separate per le parti che richiedono un isolamento più forte.

**Fino a dove inoltrare il token di un utente.** Tratti l'access token dell'utente come una credenziale, non come contesto della richiesta. Lo inoltri al massimo di un passaggio, dal client al bordo della Sua API (il gateway o il primo servizio). I servizi più in profondità in una catena di chiamate dovrebbero trovarsi dietro l'audience condivisa dell'API logica oppure ricevere un token più ristretto emesso tramite token exchange; ogni passaggio aggiuntivo compiuto dal token originale amplia i punti in cui un token trapelato può essere riutilizzato.

## Token exchange [#token-exchange]

Il token endpoint supporta **OAuth 2.0 Token Exchange** (RFC 8693), così che un servizio possa chiamare un'API a valle per conto di un utente che ha effettuato l'accesso senza inoltrare il token originale: l'applicazione scambia un access token utente già in suo possesso con un nuovo token, più ristretto, destinato a un'altra API.

Il grant è deliberatamente limitato al **downscoping**:

- Solo un'applicazione **web** (confidential) può utilizzarlo, e solo quando **Token exchange** è attivato tra i suoi tipi di grant (vedere [Applicazioni](https://dts-identity.com/it/docs/integrations/applications.md)).
- Il subject token deve essere un **access token utente ancora valido, emesso alla stessa applicazione** che esegue lo scambio. Lo scambio di token di altre applicazioni, di token senza utente o la delega con un `actor_token` non sono supportati.
- La richiesta indica **esattamente un'API di destinazione** tramite `resource`. La [policy di accesso delegato dall'utente](#user-delegated-access) dell'API di destinazione si applica all'applicazione che esegue lo scambio come per qualsiasi altra token request.
- Il token emesso **non è mai più ampio del subject token**: i suoi scope sono l'intersezione tra gli scope richiesti, gli scope del subject token, gli scope dell'API di destinazione e ciò a cui l'utente ha diritto.
- Il nuovo token resta legato allo stesso utente e alla stessa sessione e segue le impostazioni di durata dei token dell'API di destinazione.

Esempio di richiesta verso il token endpoint (l'applicazione si autentica come di consueto, ad esempio con il proprio client secret):

```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.read
```

La risposta contiene il nuovo `access_token` insieme a `expires_in` e allo `scope` effettivamente concesso.

## Scope e autorizzazioni [#scopes-vs-permissions]

Definire uno scope su un'API lo rende solo *richiedibile*, ma non concede a nessuno l'accesso. Ciò che finisce effettivamente in un token viene deciso separatamente:

- **Per i token machine-to-machine**, il token contiene esattamente gli scope autorizzati dal client grant dell'applicazione (vedere [Concedere l'accesso a un'applicazione](#granting-an-application)). Un client macchina non ha utente né ruoli, quindi **assegnare un ruolo a un'applicazione machine-to-machine non ha alcun effetto**: i suoi scope provengono esclusivamente dal grant.
- **Per i token legati a un utente** (emessi quando un'app interattiva richiede un token per conto di un utente che ha effettuato l'accesso), il [controllo degli accessi basato sui ruoli](#role-based-access-control) decide a quali scope l'utente ha diritto. Gli scope che finiscono nel token sono l'**intersezione** tra ciò che l'applicazione ha richiesto e ciò a cui l'utente ha diritto.

Questa è la risposta abituale alla domanda *"perché lo scope che ho richiesto manca senza alcun avviso nel mio token?"*: lo scope è stato richiesto, ma il chiamante non vi aveva diritto, quindi è stato scartato anziché rifiutato.

> **Difesa in profondità:** uno scope presente in un token è una *concessione*, non una garanzia. La Sua API dovrebbe comunque applicare i propri controlli a livello di oggetto (*questo* utente è proprietario di *questo* record?); un token valido con uno scope ampio non sostituisce l'autorizzazione sulla risorsa stessa.

## Controllo degli accessi basato sui ruoli [#role-based-access-control]

> **Nota sul piano:** Il controllo degli accessi basato sui ruoli è disponibile a partire dal piano Advanced (e nel Trial).

Una Custom API può attivare RBAC, che consente alla piattaforma di incorporare i ruoli e le autorizzazioni di un utente direttamente nei token che emette per quell'API. Nella scheda delle impostazioni dell'API:

- **Includi ruoli e autorizzazioni (RBAC)** lo attiva per l'API.
- **Includi il claim permissions** include gli scope concessi all'utente per questa API come claim `permissions`.
- **Includi il claim roles** include i nomi dei ruoli dell'utente come claim `roles`.

Questi claim vengono aggiunti solo ai token **legati a un utente**. L'applicazione prende poi le decisioni di autorizzazione in base a tali claim. Per definire i ruoli e assegnarli a utenti e gruppi, vedere [Ruoli](https://dts-identity.com/it/docs/integrations/roles.md).

È nell'**access token** che vanno prese queste decisioni. Un claim `roles` arriva anche nell'ID token quando un'applicazione richiede lo scope `roles`, ma quello serve solo alla presentazione, vedere [Applicare l'autorizzazione sull'access token, non sull'ID token](https://dts-identity.com/it/docs/integrations/roles.md#enforce-on-the-access-token-not-the-id-token).

## L'API come contratto verificabile [#the-api-as-a-verifiable-contract]

Un'API registrata è, di fatto, un contratto tra Lei e il resource server:

- Il suo **identificatore** è stabile e diventa l'**audience** di ogni token emesso per essa.
- La piattaforma **firma** ogni token con la propria chiave di firma (vedere [Chiavi di firma](https://dts-identity.com/it/docs/settings/signing-keys.md)).
- Il resource server convalida il token prima di fidarsi di qualsiasi scope: verifica la **firma**, che l'**issuer** sia questa piattaforma e che l'**audience** corrisponda al proprio identificatore, quindi legge gli scope.

Se uno qualsiasi di questi controlli fallisce, il resource server dovrebbe rifiutare la richiesta senza eccezioni.

## Chiamare l'API di gestione (guida rapida machine-to-machine) [#call-the-management-api-machine-to-machine-quickstart]

Per consentire a uno script o a un servizio backend di chiamare l'API di gestione della piattaforma:

1. Crei un'applicazione **machine-to-machine**, vedere [Applicazioni](https://dts-identity.com/it/docs/integrations/applications.md).
2. Nella scheda Accesso all'applicazione della **System API**, conceda a tale applicazione gli scope di gestione di cui ha bisogno (ad esempio `users.read`, `groups.write`). Conceda solo gli scope effettivamente utilizzati dall'integrazione.
3. Dal Suo servizio, richieda un token con il grant **client credentials** verso il token endpoint, utilizzando l'identificatore della System API come **audience**.
4. Chiami gli endpoint di gestione sotto `/api/v1/...` con il token restituito nell'header `Authorization: Bearer`.

La scheda **Test** della System API genera esattamente questi due comandi, precompilati con un'applicazione reale: li copi come punto di partenza.

Un token smette di funzionare prima della scadenza non appena l'applicazione perde il proprio accesso alla System API, il suo client secret viene ruotato oppure l'applicazione viene eliminata. Il servizio riceve allora `HTTP 401` e deve richiedere un nuovo token.

## Limiti dei token machine-to-machine [#machine-to-machine-token-limits]

Ai token emessi tramite il grant client credentials si applicano due limiti. Entrambi sono visibili nella panoramica **Integrazioni → API**. I token per gli accessi interattivi degli utenti non sono mai interessati da nessuno dei due.

**Richieste di token al minuto, per client**: il limite di throughput. Le richieste oltre tale limite ricevono una risposta `HTTP 429` con un header `Retry-After`; il client può riprovare una volta trascorso il tempo di attesa indicato nell'header.

| Piano | Richieste di token al minuto |
|---|---|
| Trial | 30 |
| Free | 60 |
| Essential | 1.200 |
| Advanced | 6.000 |
| Pro | 30.000 |

**Token al mese, per l'intero tenant**: un budget di volume che esiste solo nei piani di ingresso. Copre tutte le applicazioni machine-to-machine e tutte le API insieme e viene azzerato il 1° di ogni mese. Una volta esaurito, le ulteriori richieste client credentials ricevono la risposta `access_denied` fino all'inizio del mese successivo.

| Piano | Token al mese |
|---|---|
| Trial / Free | 1.000 |
| Essential e superiori | Illimitati |

Un client che memorizza nella cache il proprio access token per l'intera durata del token necessita di circa 720 token al mese e resta ben al di sotto di entrambi i limiti, quindi di norma uno dei due viene raggiunto solo da un client che richiede un nuovo token per ogni singola chiamata API. Memorizzi il token nella cache del servizio chiamante e lo riutilizzi fino a poco prima della scadenza; la durata del token si configura per ogni API nella scheda delle impostazioni dell'API.

## Riferimento per sviluppatori / API

La piattaforma include una documentazione API interattiva integrata nel prodotto all'indirizzo **/admin/api-docs**. Elenca ogni endpoint di gestione con i relativi parametri, consente di provare le chiamate nel browser e permette di scaricare dalla stessa pagina la definizione OpenAPI in formato leggibile dalle macchine.

L'API di gestione copre l'amministrazione di utenti, gruppi, organizzazioni, applicazioni, ruoli, log e dispositivi. Utilizzi **/admin/api-docs** come riferimento autorevole per gli endpoint, anziché un elenco statico in questa pagina.

## Riferimento

| Termine | Significato |
|---|---|
| Identificatore (audience) | Il valore che identifica l'API; compare nei token emessi per essa. |
| Scope / autorizzazione | Una singola capacità che un token può contenere. |
| User policy | Se le applicazioni interattive possono ottenere token per conto di un utente. |
| Client policy | Se le applicazioni possono ottenere token per sé stesse (machine-to-machine). |
| Grant | Un'autorizzazione esplicita di un'applicazione a chiamare questa API con scope specifici. |
| RBAC | L'incorporazione dei ruoli e delle autorizzazioni di un utente nei token dell'API. |
| Token exchange | Lo scambio di un access token utente con un token più ristretto destinato a un'altra API (RFC 8693). |

## Risoluzione dei problemi

- **La token request viene rifiutata con uno scope non valido.** Un'applicazione può richiedere solo gli scope che le sono stati concessi sull'API. Aggiunga lo scope al grant dell'applicazione per questa API, quindi richieda un nuovo token.
- **Le chiamate restituiscono un errore di scope insufficiente anche se è stato emesso un token.** Una richiesta riesce solo se il token contiene effettivamente lo scope richiesto dall'endpoint. Decodifichi il token e verifichi che gli scope concessi lo includano; gli scope non concessi all'applicazione vengono scartati dal token senza alcun avviso.
- **Il token ha l'audience sbagliata.** Il token deve essere richiesto per l'identificatore (audience) di questa API. Un token emesso per un'altra API, o senza audience, non viene accettato qui.
- **Il test del token non restituisce nulla o restituisce un errore.** Il test emette un token per l'applicazione e gli scope selezionati. Si assicuri che l'applicazione disponga di un grant attivo su questa API e che sia selezionato almeno uno scope.
- **Un token exchange viene rifiutato.** Il subject token deve essere un access token legato a un utente, ancora valido ed emesso alla stessa applicazione che esegue lo scambio; l'applicazione deve avere attivato il grant token exchange e la richiesta deve indicare esattamente un'API di destinazione tramite `resource`. I token machine-to-machine (senza utente) non possono essere scambiati.

Vedere anche il [glossario](https://dts-identity.com/it/docs/reference/glossary.md).
