Passa al contenuto principale

Scope e autorizzazioni

Quando crei un client OAuth2, oltre al nome devi scegliere gli scope da autorizzare. Gli scope definiscono quali operazioni quel client può eseguire tramite API.

In pratica, uno scope è un permesso: un client può ottenere un access token valido, ma riuscirà a usare solo gli endpoint compatibili con gli scope che gli hai assegnato.

Come funzionano gli scope​

Le API utilizzano OAuth2 con flusso Client Credentials e supportano un insieme di scope definiti nella specifica, ad esempio account:read, domains:read, domains:write, hosting:read, hosting:write, payment:read, pec:write, shop:read e molti altri.

Gli scope seguono quasi sempre una convenzione chiara:

  • :read per leggere dati e consultare risorse;
  • :write per creare, modificare o eliminare dati.

Per esempio:

  • domains:read consente di consultare domini e informazioni correlate;
  • domains:write consente operazioni di modifica sui domini;
  • hosting:read consente di leggere dati di hosting;
  • hosting:write consente di cambiare configurazioni o creare ed eliminare risorse.

Non tutte le aree espongono necessariamente sia :read sia :write: gli scope disponibili sono sempre quelli definiti dalla piattaforma.

Come capire quale scope serve per un endpoint​

Nelle pagine tecniche auto-generate da OpenAPI, ogni endpoint indica quali scope richiede.

Questo è il modo più affidabile per capire quali permessi assegnare al client prima di iniziare lo sviluppo.

Alcuni esempi presenti nella specifica:

  • GET /api/v3/account richiede account:read;
  • GET /api/v3/domains richiede domains:read;
  • endpoint di modifica sotto l'area domini, come operazioni DNSSEC o modifica contatti, richiedono domains:write;
  • GET /api/v3/hostings richiede hosting:read;
  • operazioni di modifica in area hosting, come creazione di risorse o aggiornamento configurazioni, richiedono hosting:write.

In altre parole, non devi scegliere gli scope "a intuito": conviene sempre partire dagli endpoint che vuoi usare e verificare gli scope richiesti nella documentazione.

Scegliere gli scope corretti​

La regola consigliata è semplice: assegna solo gli scope realmente necessari.

Un client con meno permessi è più sicuro, più facile da controllare e riduce il rischio di utilizzi impropri o accidentali.

Per esempio:

  • se devi solo leggere l'elenco dei domini, è sufficiente domains:read;
  • se devi anche modificare record DNS o contatti, serve anche domains:write;
  • se la tua integrazione consulta hosting e domini, il client può avere più scope insieme, ad esempio domains:read hosting:read.

Read e write: differenza pratica​

In generale:

  • gli endpoint GET richiedono spesso uno scope :read;
  • gli endpoint POST, PATCH, PUT o DELETE richiedono spesso uno scope :write.

È una regola pratica utile, ma la documentazione tecnica dell'endpoint resta sempre il riferimento principale.

Un client può avere più scope​

Sì. Un singolo client OAuth2 può essere autorizzato su più scope contemporaneamente.

Questo è utile quando una stessa integrazione deve lavorare su aree diverse della piattaforma, per esempio:

domains:read domains:write hosting:read

Quando richiedi un access token, assicurati che gli scope richiesti siano coerenti con quelli autorizzati sul client.

Esempi pratici​

Integrazione sola lettura​

Se devi creare un'integrazione che consulta dati senza effettuare modifiche, puoi limitarti a scope di lettura, ad esempio:

account:read domains:read hosting:read

Questo approccio è ideale per dashboard, sincronizzazioni in sola lettura o strumenti di monitoraggio.

Integrazione operativa su domini​

Se oltre a leggere i domini devi anche aggiornare configurazioni o contatti, puoi usare:

domains:read domains:write

Integrazione operativa su hosting​

Se devi leggere informazioni di hosting ma anche intervenire su configurazioni o risorse, puoi usare:

hosting:read hosting:write

Cosa succede se lo scope non è corretto​

Un endpoint può rispondere con errore anche se il client è stato creato correttamente.

I casi più comuni sono:

  • 401 Unauthorized: token assente, non valido o non più utilizzabile;
  • 403 Forbidden: token valido, ma non autorizzato per l'operazione richiesta.

Quando succede, la prima verifica da fare è questa:

  1. controlla quale scope richiede l'endpoint nella documentazione;
  2. controlla quali scope hai autorizzato sul client;
  3. verifica che la richiesta del token e la chiamata API stiano usando quel client corretto.

Quando conviene creare un nuovo client​

In molti casi è preferibile creare client separati invece di usare un solo client per tutto.

Per esempio:

  • un client per integrazioni in sola lettura;
  • un client per operazioni gestionali;
  • un client dedicato a un'applicazione o a un ambiente specifico.

Questo rende più semplice:

  • limitare i permessi;
  • ruotare o revocare un client senza impattare altri usi;
  • capire meglio dai log quale applicazione ha effettuato una chiamata.

Buone pratiche​

  • assegna solo gli scope strettamente necessari;
  • evita di concentrare troppi permessi su un unico client;
  • usa client distinti per integrazioni diverse, quando utile;
  • rivedi periodicamente gli scope autorizzati;
  • se un'integrazione cambia nel tempo, aggiorna di conseguenza anche i permessi del client.

In sintesi​

Gli scope sono il meccanismo con cui controlli cosa può fare un client OAuth2.

Per lavorare correttamente:

  • individua gli endpoint che ti servono;
  • verifica gli scope richiesti nelle pagine tecniche;
  • autorizza il client solo sui permessi necessari;
  • testa sempre che il token ottenuto sia coerente con le operazioni che vuoi eseguire.

Una buona gestione degli scope rende l'integrazione più sicura, più chiara e più facile da mantenere.