code monouso, che viene poi scambiato con un OAuth access token.
L’OAuth access token viene utilizzato per accedere alle API delle risorse dell’account; per chiamare le API dei modelli, utilizza la relativa API Key. L’autorizzazione OAuth non crea automaticamente API Key, non attiva servizi né aumenta il saldo.
Scegliere il metodo di integrazione
Il reindirizzamento standard non richiede
embed=studio, embed_origin o postMessage. La modalità componente Studio prevede che l’host crei la pagina di autorizzazione e mantenga il bridge dei messaggi; le terze parti si integrano secondo il protocollo del componente alla fine di questo documento e non devono concatenare autonomamente questi due parametri.
Endpoint e documento di discovery
L’interfaccia di gestione delle applicazioni richiede l’autenticazione con l’account e non è un’interfaccia di registrazione dinamica anonima (DCR). Gli endpoint di discovery/registrazione del servizio MCP stesso sono punti di accesso diversi dagli endpoint OAuth dell’account in questa tabella; quando ti connetti a uno specifico MCP, segui la documentazione e i risultati della discovery di quel servizio.
Il documento di discovery viene utilizzato per ottenere endpoint e capacità del protocollo. Il flusso corrente restituisce OAuth token, non restituisce
id_token; non gestire il processo come un flusso di accesso OpenID Connect completo solo perché esiste lo scope openid.
Ambiti di autorizzazione: utilizzare i nomi scope correnti
scope è un insieme di nomi di autorizzazione separati da spazi e sensibili alle maiuscole/minuscole. Le nuove applicazioni utilizzano autorizzazioni specifiche come profile:read, email:read, phone:read.
Da dove ottenere le autorizzazioni richiedibili
Dopo l’accesso, l’interfaccia dell’elenco delle applicazioni OAuthGET /api/v1/oauth2/applications/ restituisce available_scopes; il selettore delle autorizzazioni nella pagina di gestione delle applicazioni utilizza lo stesso catalogo. Questi sono gli ambiti facoltativi che dovrebbero essere adottati dalle normali applicazioni self-service.
scopes_supported di Discovery include tutti i nomi delle autorizzazioni riconosciute dalla piattaforma, ma non significa che la tua applicazione possa richiederle tutte. L’autorizzazione effettiva controlla contemporaneamente:
- se l’autorizzazione può essere delegata a questo tipo di applicazione;
- se l’autorizzazione è stata registrata negli ambiti consentiti di questa applicazione OAuth;
- se l’utente corrente possiede l’autorizzazione richiesta.
invalid_scope. Vengono ricontrollate anche durante lo scambio del codice di autorizzazione e l’aggiornamento, e le autorizzazioni non vengono completate o elevate automaticamente.
Autorizzazioni facoltative per le normali applicazioni self-service
Di seguito è riportato il catalogo corrente (2026-10-09); durante l’integrazione, fai riferimento aavailable_scopes.
Ad esempio, per leggere solo il profilo personale usa
profile:read; per l’email aggiungi email:read; per leggere le API Key esistenti usa profile:read credentials:read. Richiedi credentials:write solo quando è effettivamente necessario creare o modificare Key, e aggiungi offline_access quando è necessario l’aggiornamento.
Alcune autorizzazioni sono disponibili solo per applicazioni affidabili approvate dalla piattaforma, ad esempio sites:read, sites:write, platform-tokens:read; altre autorizzazioni non sono aperte alle normali applicazioni OAuth di terze parti. I tipi di client public/confidential descrivono se è possibile custodire un secret e non sono correlati al fatto che l’applicazione sia affidabile. Le applicazioni create self-service non possono attivare autonomamente autorizzazioni affidabili.
account è il selettore delle autorizzazioni dell’account utilizzato dal MCP ufficiale designato per la gestione dell’account, non è uno scope di “tutte le autorizzazioni” per applicazioni di terze parti e non può essere combinato con altri scope. Le terze parti devono elencare esplicitamente le autorizzazioni specifiche necessarie.
Migrazione dalla documentazione precedente
I vecchi nomi non vengono accettati come alias di compatibilità. Aggiorna contemporaneamente gli scopes registrati dell’applicazione OAuth, l’URL di autorizzazione e il controllo delle autorizzazioni interno; modificare la configurazione dell’applicazione non aggiunge autorizzazioni ai token già emessi e richiede una nuova autorizzazione dell’utente.
Passaggio 1: registrare un’applicazione OAuth
Apri Gestione applicazioni OAuth, crea un’applicazione e compila:- Nome, descrizione, logo dell’applicazione: visualizzati sul lato dell’applicazione nella pagina di autorizzazione.
- Tipo di client: per client puramente frontend, mobili o desktop selezionare Public; per servizi che possono conservare il secret nel backend selezionare Confidential.
- Indirizzo di callback: nell’ambiente di produzione usare HTTPS e registrare l’URL completo realmente gestito dall’applicazione per il callback.
- Permessi: selezionare gli scopes effettivamente necessari dall’elenco fornito dalla pagina.
client_id. I client Confidential conservano client_secret sul lato server e non possono inserirlo in HTML, variabili di build frontend o URL. I client Public non usano un secret per ottenere il token; anche se la risposta di registrazione include questo campo, non può essere trattato come una credenziale che il client possa mantenere segreta.
redirect_uri deve corrispondere esattamente nella registrazione, nell’autorizzazione e nello scambio del token, inclusi percorso, barra finale e parametri di query. Ogni account può creare al massimo 20 applicazioni. Il secret viene mostrato solo alla creazione/rotazione; dopo la rotazione, il vecchio secret non può più effettuare scambi che richiedono l’autenticazione del client.
Passaggio 2: il pulsante avvia l’autorizzazione
A ogni clic su connetti, generare nuovistate e code_verifier casuali e calcolare:
state, verifier e indirizzo di callback nella sessione dell’applicazione stessa, quindi aprire la pagina di autorizzazione con parametri codificati in URL:
plain, i client Public non possono usarlo. Anche i client Confidential sono consigliati di usare S256; se PKCE è stato usato all’avvio dell’autorizzazione, nello scambio deve essere inviato il verifier corrispondente.
Dopo il consenso dell’utente, si torna a redirect_uri, i parametri di query includono code e lo state restituito senza modifiche. In caso di rifiuto, vengono restituiti error=access_denied, una descrizione dell’errore e state. Prima di gestire il callback, verificare che state corrisponda alla sessione corrente. Il codice di autorizzazione è valido per 10 minuti e può essere scambiato una sola volta; dopo un errore, avviare nuovamente la connessione, senza aggiornare ripetutamente il vecchio URL di callback.
Passaggio 3: scambiare il token OAuth
I client Public effettuano lo scambio direttamente dal browser o dal client; i client Confidential effettuano lo scambio nel proprio backend. Il corpo della richiesta supporta la codifica form e le seguenti variabili rappresentano i dati ottenuti dall’applicazione in questa autorizzazione:client_secret sul lato server. Attualmente è supportato client_secret_post; non considerare l’autenticazione del client HTTP Basic come una modalità supportata.
Nella risposta di successo leggere access_token, token_type, expires_in e lo scope effettivamente concesso. refresh_token è disponibile solo se è stato richiesto e approvato offline_access. Non trattare l’access token OAuth come API Key dell’API del modello, né scrivere token, verifier o codice di autorizzazione nei log, negli eventi di analisi o nei link condivisi.
Passaggio 4: leggere le informazioni utente e l’API Key
Usare prima l’access token OAuth per richiedere UserInfo:id è l’identificatore dell’utente; profile:read o openid consentono di leggere i dati di base (come username, nickname, avatar, is_verified, date_joined, registration_method); per l’email è necessario email:read, mentre per il numero di telefono e la regione è necessario phone:read. Non presumere che i campi non autorizzati siano sempre presenti.
Quando è necessaria un’API Key già esistente ed è stato concesso credentials:read, usare l’id di UserInfo come condizione di filtro:
count e items, e il campo Key è items[*].token, non data[0].value. user_id=me non è un ID utente valido per questa interfaccia. Per i dati su più pagine, continuare a leggere in base a offset/limit, senza considerare la prima pagina come tutte le credenziali.
Selezionare la credenziale applicabile in base ad applicazione, servizio e stato di validità, senza prendere ciecamente la prima. Una lista vuota non significa che l’autorizzazione sia fallita; l’utente potrebbe non aver ancora creato una Key applicabile. Il controllo dei permessi dell’access token OAuth e l’ambito del servizio, le quote e le condizioni di scadenza dell’API Key stessa sono vincoli diversi.
Consentire la lettura delle API Key significa che una terza parte può salvarle e utilizzarle. Revocare la richiesta OAuth o cancellare lo stato di accesso dell’applicazione non invaliderà le API Key già copiate; l’utente deve revocare o ruotare separatamente tale Key nella gestione delle credenziali.
Esempio eseguibile di browser Public / PKCE
Distribuire la pagina seguente alREDIRECT_URI registrato, sostituendo CLIENT_ID e l’indirizzo di callback. Il pulsante avvia l’autorizzazione standard e, tornando alla stessa pagina, legge il profilo e il numero di Key esistenti. L’esempio non mostra né persiste le Key; l’applicazione di produzione consuma i risultati in base all’uso effettivo. Verificare prima in una pagina browser indipendente, quindi eseguire il collaudo secondo i requisiti iframe successivi.
sessionStorage precedentemente salvato. Le applicazioni di produzione devono gestire i token nel proprio schema di sessione, gestire la scadenza e rimuovere i parametri URL di autorizzazione dopo aver ricevuto la risposta; l’interfaccia principale della pagina deve essere renderizzata per prima e gli errori di rete devono influire solo sullo stato della connessione.
iframe nei siti white-label
Il sito del cliente reindirizza autonomamente alla pagina di autorizzazione
È sufficiente utilizzare i parametri OAuth standard e gestire il proprio callback;window.location.assign() naviga nell’iframe corrente e la pagina padre rimane nel dominio white-label. Non è necessario aggiungere embed=studio per l’icona né implementare il protocollo di messaggi Studio.
Devono essere soddisfatte le seguenti condizioni:
- La pagina dell’applicazione e la pagina di callback utilizzano HTTPS, sono effettivamente accessibili e consentono l’incorporamento tramite iframe da parte del dominio padre white-label; verificare
Content-Security-Policy: frame-ancestorseX-Frame-Optionsdi entrambe le parti. - Il sandbox consente gli script, i moduli e le capacità di origine/archiviazione richiesti dalla pagina. Quando è supportato l’accesso tramite popup, sono necessarie anche le corrispondenti capacità popup; dare priorità alla configurazione del componente Website fornito da Studio.
- Il browser consente allo scenario di incorporamento corrente di utilizzare l’archiviazione richiesta dallo stato di autorizzazione. Lo stato di accesso del sito white-label e lo stato di accesso di AuthFrontend potrebbero essere diversi; non si deve presumere che aver effettuato l’accesso al sito white-label significhi aver già effettuato l’accesso alla pagina di autorizzazione.
- Il servizio di scambio token nel callback è disponibile e le richieste cross-origin consentono l’origine dell’applicazione; DNS, CORS ed errori HTTP devono tutti mostrare uno stato riprovabile e non devono interrompere il rendering dell’intera pagina.
Utilizzare l’autorizzazione dell’account corrente di Studio
In Studio, attiva OAuth in «Impostazioni → Home → Componenti sito», quindi inserisciclient_id e l’indirizzo di callback registrato. Il sito e il callback devono utilizzare la stessa origine HTTPS e devono essere diversi dall’origine Studio. La pagina di terze parti deve:
- Inviare
acedatacloud:oauth:readyall’origin esatto del sito padre, ricevere e verificareacedatacloud:oauth:init. - Il pulsante genera state e verifier PKCE, invia
acedatacloud:oauth:authorize(state, challenge S256); il verifier rimane nella propria pagina. - Verificare finestra padre, origin e state, gestire code o error in
acedatacloud:oauth:resulte scambiarli tramite l’endpoint token standard. Studio visualizza la pagina di autorizzazione nell’area del componente; dopo il consenso dell’utente restituisce il codice di autorizzazione tramite messaggio, senza che l’applicazione debba reindirizzare. In assenza di accesso restituiscelogin_required, in caso di rifiuto restituisceaccess_denied, e in caso di timeout dell’attesa restituisceauthorization_timeout. La modifica dell’account ricrea l’iframe dell’applicazione e annulla le autorizzazioni non completate.
profile:read credentials:read e non include offline_access. Non presumere di ricevere necessariamente un refresh token. embed=studio e embed_origin sono gestiti dall’host Studio e dalla pagina di autorizzazione; la pagina del cliente deve solo rispettare il protocollo di messaggistica.
Per un esempio completo del pulsante, consulta la Guida all’integrazione OAuth dei componenti del sito Studio.
Ciclo di vita, rinnovo e revoca
Il periodo di validità predefinito dell’access token è di 15 giorni; pianifica il rinnovo o la nuova autorizzazione in base aexpires_in di ogni risposta; il refresh token è predefinito a 30 giorni e il periodo è soggetto alla configurazione del servizio. Non codificare rigidamente questi due valori come promesse permanenti.
Dopo aver ottenuto offline_access, puoi chiamare:
Errori comuni e accettazione
Prima della consegna, verifica almeno: callback corretto, rifiuto, state errato, code scaduto/già usato, assenza di Key, errore di rete, scadenza del token, assenza dello scope richiesto, nonché il primo accesso e il cambio di account nello scenario iframe. Non salvare code, token o API Key completi nelle prove di test.
Verifica in due passaggi e nuova autorizzazione
Dopo che l’utente ha attivato la verifica in due passaggi, Ace Data Cloud completerà nella pagina di autorizzazione la verifica del codice dell’autenticatore o del codice di recupero monouso, quindi consegnerà il codice di autorizzazione. La tua applicazione continua a utilizzare il flusso OAuth standard e non deve richiedere, salvare o inoltrare all’utente chiavi dell’autenticatore o codici di recupero. Quando l’utente attiva, sostituisce, disattiva la verifica in due passaggi o recupera l’account, le precedenti sessioni dell’account, i refresh token e i relativi token di autorizzazione della piattaforma potrebbero non essere più validi. Quando ricevi una sessione non valida oinvalid_grant, avvia nuovamente un flusso di autorizzazione visibile all’utente; non riutilizzare ripetutamente vecchi codici di autorizzazione e non tentare di aggirare la verifica. Il metodo di autenticazione delle normali API Key del modello rimane invariato; se sospetti che l’account sia stato compromesso, verifica e revoca separatamente le API Key interessate.
