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 del token.

Come funzionano gli scope

Le API utilizzano OAuth2 con flusso Client Credentials. Gli scope seguono una convenzione chiara:

• :read per leggere dati e consultare risorse;
• :write per creare, modificare o eliminare dati;
• :secrets per leggere dati riservati, come credenziali e chiavi private.

Per esempio:

• domains:read consente di consultare domini e informazioni correlate;
• domains:write consente operazioni di modifica sui domini, come record DNS, contatti o DNSSEC;
• hosting:read consente di leggere dati di hosting;
• hosting:write consente di cambiare configurazioni o creare ed eliminare risorse dell'hosting.

Non tutte le aree espongono tutti e tre i livelli: gli scope disponibili sono sempre quelli elencati di seguito.

Scope disponibili

Area	Scope
Account e sub-account	account:read, account:write
Fatture e note di credito	billing:read
Acquisti e task	purchases:read, purchases:write
Shop, ordini e TLD	shop:read, shop:write
Pagamenti, One-Click e credito prepagato	payment:read, payment:write
Domini e DNS	domains:read, domains:write, domains:secrets
Hosting	hosting:read, hosting:write, hosting:secrets
Server	server:read, server:write, server:secrets
Cloud Storage	cloudstorage:read, cloudstorage:write, cloudstorage:secrets
Object Storage	objectstorage:read, objectstorage:write, objectstorage:secrets
Certificati SSL	ssl:read, ssl:write, ssl:secrets
PEC	pec:read, pec:write
Microsoft 365	m365:read, m365:write
Licenze	weblicense:read
SMS	sms:read, sms:write
Monitoraggio server	servermonitoring:read, servermonitoring:write
Monitoraggio web	webmonitoring:read, webmonitoring:write
Upload di file	upload:write

L'elenco completo, con la descrizione di ogni scope, è anche nella specifica OpenAPI e nelle pagine di riferimento.

Gli scope :secrets

Alcuni dati sono particolarmente delicati: credenziali di hosting e server, chiavi private dei certificati, chiavi segrete S3, password degli utenti dei cloud storage, authcode dei domini. Per leggerli non basta lo scope :read dell'area: serve anche il relativo scope :secrets.

In pratica:

• gli endpoint dedicati ai segreti, come GET /api/v3/hostings/{hosting_id}/credentials o GET /api/v3/ssl-certificates/{ssl_certificate_id}/keys, richiedono sia lo scope :read sia lo scope :secrets;
• negli altri endpoint il dato riservato viene restituito null se il token non ha lo scope :secrets, mentre il resto della risposta è completo.

Assegna gli scope :secrets solo ai client che hanno davvero bisogno di leggere quei dati.

Lo scope api:full

api:full non è uno scope da assegnare al client, ma una scorciatoia da usare nella richiesta del token: chiede tutti gli scope assegnati al client.

Se nella richiesta del token ometti il parametro scope, il risultato è lo stesso: il token riceve tutti gli scope del client.

Scope del client e scope del token

Gli scope compaiono in due punti diversi:

• sul client: sono i permessi massimi che il client può ottenere, scelti quando lo crei nel Manager;
• sul token: sono i permessi effettivi della singola sessione, scelti nella richiesta a /oauth/token.

Nella richiesta del token puoi chiedere tutti gli scope del client oppure solo una parte. Se chiedi uno scope che non è assegnato al client, l'endpoint del token risponde con errore invalid_scope e non emette il token.

La risposta del token contiene, nel campo scope, l'elenco degli scope effettivamente concessi.

Come capire quale scope serve per un endpoint

Nelle pagine che descrivono la specifica di ogni endpoint API presenti in questa guida è sempre indicato quali scope richiede ogni chiamata API. Vedi il seguente esempio:

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

Alcuni esempi:

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

Se un endpoint richiede più scope, servono tutti.

Anche la risposta di errore aiuta: quando il token non ha gli scope necessari, l'header WWW-Authenticate della risposta 403 indica gli scope richiesti dall'endpoint.

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.

Operazioni asincrone e task

Alcune operazioni, come il riavvio di un server o il ripristino di un backup, vengono eseguite in background: l'endpoint risponde subito con un task, di cui puoi seguire l'avanzamento con GET /api/v3/tasks/{task_id}.

La lettura dei task richiede lo scope purchases:read, qualunque sia lo scope dell'operazione che li ha avviati. Se la tua integrazione avvia operazioni asincrone e ne vuole seguire l'esito, aggiungi quindi purchases:read al client.

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

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

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 server

Se devi gestire i server, ad esempio riavviarli e seguire l'esito dell'operazione, puoi usare:

server:read server:write purchases:read

Integrazione amministrativa

Se devi scaricare fatture e note di credito, ad esempio per importarle in un gestionale, è sufficiente:

billing:read

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 (errore 1100): token assente, scaduto, revocato o non valido. Richiedi un nuovo token;
• 403 Forbidden con errore 1101: il token è valido, ma non include gli scope richiesti dall'endpoint;
• 403 Forbidden con errore 1601: il token è valido, ma l'operazione non è consentita, ad esempio perché la funzione non è inclusa nel servizio, non è disponibile per i sub-account o la richiesta arriva da un IP non autorizzato.

Un 403 non cambia richiedendo un nuovo token con lo stesso client: bisogna cambiare gli scope, il client o i permessi.

Quando ricevi un errore di scope, la prima verifica da fare è questa:

1. controlla quale scope richiede l'endpoint nella documentazione, o nell'header WWW-Authenticate della risposta;
2. controlla quali scope hai autorizzato sul client;
3. controlla quali scope hai chiesto nella richiesta del token, nel campo scope della risposta;
4. verifica che la richiesta del token e la chiamata API stiano usando il 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.

Gli scope di un client non si modificano dopo la creazione: se un'integrazione ha bisogno di permessi diversi, crea un nuovo client con gli scope corretti.

Buone pratiche

• assegna solo gli scope strettamente necessari;
• assegna gli scope :secrets solo quando servono davvero;
• evita di concentrare troppi permessi su un unico client;
• usa client distinti per integrazioni diverse, quando utile;
• nella richiesta del token chiedi solo gli scope che servono a quella sessione;
• rivedi periodicamente gli scope autorizzati;
• se un'integrazione cambia nel tempo, crea un client con i nuovi permessi ed elimina quello precedente.

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.