Cosa è cambiato nel meccanismo di aggiornamento del token offline di Shopify?
Se di recente stai gestendo il codice di autorizzazione di un’app Shopify, questo aggiornamento merita di essere esaminato con attenzione.
Il 10 dicembre 2025, Shopify ha specificato nel changelog per sviluppatori: il token di accesso offline ora supporta la scadenza e l’aggiornamento. Entro il 20 marzo 2026, un altro changelog ha aggiunto un avvertimento più severo: dopo il 1 aprile 2026, le nuove app pubbliche create e che chiamano l’API Admin devono utilizzare un token di accesso offline che scade.
Non si tratta di una modifica che interromperà immediatamente tutte le vecchie applicazioni. Le app pubbliche esistenti, le app personalizzate e le app create dai commercianti nel backend non rientrano in questa regola del 1 aprile. Tuttavia, se stai creando una nuova applicazione o aprendo una nuova app pubblica quest’anno, è meglio integrare questa logica di aggiornamento fin dalla prima versione.
L’ipotesi di “installare e usare per sempre” è finita
Molti compiti di backend delle app Shopify dipendono dal token offline. Ad esempio, sincronizzazione degli ordini, gestione dei webhook, estrazione programmata dei prodotti e generazione di report per il negozio. Quando il commerciante non è online, l’app deve comunque poter chiamare l’API Admin, quindi il token offline è sempre stata la scelta predefinita.
La gestione comune nel codice precedente era semplice: il commerciante ottiene il token al momento dell’installazione e lo memorizza nel database; successivamente, ogni volta che richiede l’API Admin, lo inserisce nell’intestazione X-Shopify-Access-Token. Finché il commerciante non disinstalla l’app, il team di solito presume che questo token possa ancora essere utilizzato.
Il nuovo token offline che scade ha smantellato questa ipotesi. La documentazione ufficiale ora è molto chiara: il token di accesso offline che scade ha una validità di 1 ora, e il campo expires_in nella risposta è 3600. Viene restituito anche un refresh_token, che l’app può utilizzare per ottenere un nuovo token di accesso senza disturbare il commerciante.
Ad esempio, un sito indipendente che vende articoli per animali domestici, con circa duecento SKU, esegue la sincronizzazione dell’inventario ogni 15 minuti. In precedenza, il compito di sincronizzazione doveva solo leggere il token offline dalla tabella del negozio. Ora deve almeno controllare due campi in più: quando scade il token di accesso e se il refresh token è ancora valido. Altrimenti, il compito di sincronizzazione notturno che incontra per la prima volta un 401 potrebbe fermare l’intero inventario per tutta la notte.
L’aggiornamento non richiede di ripetere il processo di installazione
Un punto chiave di questa modifica di Shopify è che l’aggiornamento avviene nell’endpoint del token, senza richiedere al commerciante di autorizzare nuovamente.
L’endpoint del token OAuth fornito dalla documentazione ufficiale è:
POST https://{shop}.myshopify.com/admin/oauth/access_token
Se stai utilizzando lo scambio di token, puoi includere requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token quando ottieni il token offline e impostare expiring su 1. Se utilizzi il grant del codice di autorizzazione, richiedi anche un token offline che scade passando expiring=1 durante lo scambio del codice.
Nella risposta, non è sufficiente salvare solo l’access_token. Devi anche salvare almeno questi elementi:
• expires_in: il numero di secondi rimanenti per l’attuale token di accesso, che ora è di 3600 secondi secondo l’ufficiale
• refresh_token: necessario per il prossimo aggiornamento del server
• refresh_token_expires_in: la validità iniziale del refresh token, che secondo l’ufficiale è di 7776000 secondi, ovvero 90 giorni
Non scrivere mai 3600 come valore fisso. L’ufficiale avverte anche che l’app dovrebbe leggere expires_in dalla risposta e non presumere che la validità rimanga invariata.
Il rischio maggiore è il refresh concorrente
La logica di aggiornamento sembra piuttosto comune, ma il vero problema si presenta durante la rotazione.
La documentazione di Shopify è molto dettagliata: ogni volta che si effettua un refresh, verranno restituiti un nuovo access token e un nuovo refresh token. L’app deve memorizzare entrambi, utilizzando il nuovo refresh token per il prossimo aggiornamento.
Il vecchio refresh token non scade immediatamente nel secondo in cui Shopify emette un nuovo token. Scadrà nel primo momento in cui si verifica una delle seguenti condizioni: l’app ha utilizzato il nuovo refresh token; l’app ha nuovamente ottenuto un nuovo token tramite lo scambio di token o il grant del codice di autorizzazione; il vecchio refresh token è stato utilizzato per la prima volta per un refresh dopo 30 giorni; oppure scade il suo periodo originale di 90 giorni.
Questa regola ha un impatto diretto sull’implementazione. Supponiamo che il tuo worker webhook e il compito programmato scoprano contemporaneamente che il token sta per scadere, e entrambi i processi tentano di effettuare un refresh. Entrambi scrivono il risultato nel database, e quello che scrive per ultimo sovrascriverà il precedente. La prossima richiesta potrebbe dipendere da quale refresh token viene utilizzato, a causa della competizione.
Un approccio più sicuro è bloccare a livello di negozio o fare un aggiornamento condizionale nel database: consenti di scrivere un nuovo token solo se il refresh token attuale è quello che hai appena letto. In caso di fallimento del refresh, leggi nuovamente il record e non espellere immediatamente il commerciante da OAuth.
Il 401 non è l’unico punto di attivazione
Aggiornare solo dopo aver ricevuto un 401 può salvare alcune richieste, ma i compiti di backend subiranno un ulteriore fallimento. Questo va bene per i webhook e altri compiti che hanno un meccanismo di ripetizione, ma per le esportazioni manuali o gli aggiornamenti di massa, l’esperienza sarà piuttosto scadente.
L’ufficiale consiglia di effettuare un refresh alcuni minuti prima e di ripetere il refresh in caso di ricezione di un 401. Nella pratica, puoi memorizzare expires_at per ogni negozio e controllare prima della richiesta se sta per scadere. Ad esempio, se mancano meno di 5 minuti alla scadenza, effettua prima un refresh e poi richiedi l’API Admin.
In caso di fallimento del refresh, è necessario inviare un avviso separato. Le cause potrebbero essere il refresh token scaduto, il client secret ruotato, il commerciante che disinstalla l’app, oppure il tuo sistema di memorizzazione che non ha salvato correttamente il nuovo refresh token. Tutti questi eventi possono manifestarsi come un 401, ma il modo di gestirli è diverso.
Le vecchie applicazioni possono prendersi una pausa, ma non accumulare ulteriori debiti tecnici
La richiesta del 1 aprile 2026 si applica solo alle nuove app pubbliche. Shopify ha anche specificato che le app pubbliche create prima del 1 aprile non saranno temporaneamente influenzate.
Tuttavia, nella documentazione sui token di accesso c’è un’altra scadenza: le app pubbliche devono utilizzare il token di accesso offline che scade per richiedere l’API Admin entro il 1 gennaio 2027. Le app personalizzate e quelle create dai commercianti non rientrano in questo ambito.
Quindi, le vecchie applicazioni non devono migrare immediatamente, ma se stai già modificando il livello di autorizzazione, è meglio sistemare la struttura della tabella e il percorso di aggiornamento. Almeno, rimuovi commenti come “il token offline non scade mai” e non classificare più il 401 come disinstallazione dell’app da parte del commerciante nei compiti di backend.
Non ho ancora provato a confermare riga per riga l’implementazione interna della libreria più recente in un progetto Shopify reale. L’ufficiale afferma che se utilizzi i template e le librerie delle app Shopify, questa parte è già stata gestita. I progetti che utilizzano OAuth personalizzato, vecchie app Rails o che hanno modificato il livello di autorizzazione del template dovrebbero comunque controllare il percorso di memorizzazione e aggiornamento del token.
Puoi iniziare a modificare questi punti
Non è necessario riscrivere l’intero sistema di autorizzazione all’inizio. Inizia a controllare quattro aree:
• Se nel database c’è uno spazio per memorizzare refresh_token, expires_at, refresh_token_expires_at
• Nella libreria di incapsulamento delle richieste API Admin, se è possibile controllare il tempo di scadenza prima della richiesta
• Se i compiti di backend e i worker webhook possono aggiornare contemporaneamente il token dello stesso negozio
• Nella registrazione dei 401, se è possibile distinguere tra token scaduto, scope insufficiente e disinstallazione dell’app
Se l’app sta ancora utilizzando un token offline non scadente, la nuova versione può iniziare ad aggiungere expiring=1 durante l’installazione o lo scambio di token, e poi collegare la logica di aggiornamento a un client API unificato. In questo modo, la sincronizzazione dei prodotti, degli ordini e dei compiti di report non richiederanno di scrivere il codice di aggiornamento separatamente.
Questa modifica non è appariscente, ma sembra che Shopify stia portando l’autorizzazione delle app verso comportamenti OAuth più standardizzati. I compiti di backend possono continuare a funzionare, ma in futuro non potranno più fare affidamento su un token permanente per sostenere l’intero ciclo di vita.
Fonti ufficiali:
• https://shopify.dev/changelog/offline-access-tokens-now-support-expiry-and-refresh
• https://shopify.dev/changelog/expiring-offline-access-tokens-required-for-public-apps-april-1-2026
• https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens