E-commerce13 minutes de lecture

Jetons d’accès Shopify : migrer sans interrompre l’application

Migrez les jetons Shopify hors ligne : rotation, stockage atomique, reprise, restrictions IP et huit scénarios pour protéger les flux de l’application.

Relais de modules en verre fumé passant par un anneau de rotation sur une voie e-commerce

La migration des jetons d’accès Shopify ne se résume pas à activer leur expiration. Une application publique doit savoir renouveler son accès, enregistrer chaque nouvelle paire de jetons sans état intermédiaire, reprendre après une réponse perdue et prouver qu’aucun ancien worker n’utilise encore le jeton permanent.

Shopify fixe le 1er janvier 2027 comme date limite pour les applications publiques qui appellent l’Admin API avec un jeton hors ligne non expirant. Les applications non conformes seront alors retirées de l’App Store et bloquées pour les nouvelles installations. Les marchands concernés verront un avertissement à partir du 15 janvier, puis les appels avec un ancien jeton recevront une erreur HTTP 403 à partir du 1er avril 2027.

Ce guide transforme cette échéance en protocole durable : une matrice de migration, huit scénarios dégradés et une décision de sortie pour préserver les commandes, stocks, traductions ou synchronisations confiés à l’application.

Quelles applications Shopify doivent migrer ?

La règle concerne les applications publiques qui utilisent encore un jeton hors ligne non expirant pour appeler l’Admin API. Elle s’applique aussi aux applications publiques créées avant le 1er avril 2026. Shopify exclut de cette obligation les applications personnalisées, les applications créées par un marchand dans le Dev Dashboard ou l’administration et les jetons en ligne.

Cette frontière doit être vérifiée installation par installation. Le nom donné en interne à une intégration — privée, partenaire, connecteur ou application maison — ne prouve pas son mode de distribution ni le type de jeton réellement présenté à l’API.

Un jeton hors ligne sert aux actions exécutées sous l’autorité de l’application sans session active d’un membre de l’équipe : tâche planifiée, consommateur de webhook, synchronisation ERP, action Shopify Flow ou traitement d’un catalogue. Un jeton en ligne reste lié à la personne connectée et à ses permissions. Remplacer mécaniquement l’un par l’autre peut donc modifier le responsable de l’action ou interrompre les traitements en arrière-plan.

Commencez par relever quatre faits dans le Dev Dashboard et dans le code déployé :

  • le mode de distribution de l’application ;
  • les API réellement appelées et les scopes accordés ;
  • la manière dont chaque jeton a été acquis ;
  • les workers, régions et tâches qui présentent encore ce jeton.

Le calendrier ne doit pas être lu comme trois reports successifs. Shopify précise que le 1er janvier reste la date de migration. Les avertissements et le rejet d’avril donnent aux marchands le temps de se préparer ; ils ne transforment pas un jeton permanent en solution acceptable jusqu’au dernier jour.

Pourquoi la rotation change-t-elle l’architecture de l’application ?

Un ancien jeton hors ligne reste utilisable jusqu’à la désinstallation de l’application ou la révocation de son secret. Sa fuite ouvre donc une fenêtre longue. Le nouveau jeton d’accès expire selon la durée retournée par Shopify — une heure dans la documentation actuelle — et s’accompagne généralement d’un jeton de renouvellement initialement valable 90 jours.

La réduction de cette fenêtre limite l’effet d’un jeton d’accès volé. Elle ajoute aussi une responsabilité : l’application doit renouveler, stocker et distribuer la nouvelle valeur sans perdre la continuité.

Le point critique n’est pas le bouton d’activation. C’est la transition d’un état cohérent vers le suivant :

paire actuelle valide
        ↓
demande de renouvellement unique
        ↓
réponse complète reçue
        ↓
nouvelle paire enregistrée atomiquement
        ↓
nouvelle paire distribuée aux workers
        ↓
ancienne paire retirée après preuve d’usage

Si deux workers renouvellent en parallèle, chacun peut croire posséder la valeur courante. Si la réponse arrive chez Shopify mais disparaît avant l’écriture en base, l’application peut garder une paire devenue obsolète. Si le nouveau jeton est enregistré sans sa date d’expiration ou sans son jeton de renouvellement, la panne est seulement retardée.

Shopify a renforcé le mécanisme en août 2026 : le jeton de renouvellement précédemment utilisé peut rester disponible tant que l’application n’a pas commencé à utiliser son remplaçant. Cette voie aide à reprendre après une réponse réseau perdue ou une écriture échouée. Elle ne dispense pas de sérialiser les renouvellements par boutique ni d’enregistrer la paire retournée dans une seule transaction. La période de récupération ne dépasse pas trente jours depuis la première utilisation et ne prolonge pas la durée initiale du jeton de renouvellement.

La matrice de migration des jetons Shopify

Créez une ligne par couple boutique × flux critique. Une boutique peut partager la même identité d’application tout en exposant plusieurs conséquences : synchronisation des commandes, stock, prix, contenus ou opérations de support.

Installation et flux Jeton actuel Acquisition cible Propriétaire du renouvellement Stockage et concurrence Voie de secours Preuve attendue Décision
commandes vers ERP hors ligne non expirant paire expirante par échange direct service d’identité unique transaction atomique et verrou par boutique reprise de réponse puis accès applicatif signé commande reçue une fois avant et après rotation migrer en pilote
webhook de désinstallation hors ligne non expirant paire expirante gérée par le gabarit officiel backend de l’application adaptateur de session partagé nouvelle acquisition si l’installation existe encore webhook accepté sans lecture d’un secret retiré migrer avec le socle
tâche catalogue nocturne type à confirmer accès applicatif à courte durée worker d’identité central cache borné par l’expiration retournée nouvelle acquisition avec assertion signée tâche complète puis jeton inutilisable hors fenêtre comparer les deux voies
action opérateur dans l’interface jeton hors ligne par défaut jeton en ligne si l’action doit porter les droits de la personne couche d’authentification interactive session attribuée à l’utilisateur nouvelle authentification refus lorsque le rôle ne permet pas l’action séparer du batch

La colonne « voie de secours » ne doit pas devenir une seconde chaîne d’identité oubliée. Elle répond à une panne nommée : réponse de migration perdue, jeton de renouvellement indisponible, clé révoquée ou besoin de réautorisation. Son déclenchement, ses droits et sa preuve doivent être aussi explicites que le chemin nominal.

Cette matrice complète la supervision des webhooks et API Shopify. La supervision indique qu’un flux a échoué et mesure son impact métier. La migration d’identité garantit que l’application peut encore s’authentifier, renouveler son accès et reprendre sans réintroduire un secret permanent.

Choisir entre paire renouvelable et accès applicatif

Shopify documente désormais deux voies principales pour les travaux réalisés sous l’autorité d’une application publique.

Paire de jetons expirants

L’échange de jeton ou le flux d’autorisation peut retourner un jeton d’accès à courte durée et un jeton de renouvellement. Les gabarits officiels Shopify gèrent une grande partie de ce cycle lorsqu’ils sont à jour. Une application construite autrement doit lire les durées retournées, renouveler avant l’expiration et conserver la nouvelle paire.

Cette voie convient lorsque l’application possède déjà un stockage de session fiable et un propriétaire unique du renouvellement. Elle demande de coordonner les workers : pour une même application et une même boutique, l’acquisition ou le renouvellement peut retirer des valeurs précédentes.

Accès applicatif avec assertion signée

Une application publique peut aussi demander un jeton hors ligne de courte durée en présentant une assertion signée avec sa clé privée. Il n’existe alors pas de jeton de renouvellement : le backend demande un nouvel accès lorsque nécessaire. Shopify présente notamment cette voie comme un moyen de récupérer l’accès si le jeton de renouvellement a été perdu, sans attendre que le marchand rouvre l’application.

Cette option déplace le point sensible. Le jeton obtenu expire vite, mais la clé privée peut permettre d’en demander d’autres tant que sa clé publique reste enregistrée. La rotation et la révocation des clés, le contrôle du service qui signe et la protection du stockage deviennent donc des éléments du produit.

Le choix ne se réduit pas au framework. Comparez la fréquence des traitements, le nombre de workers, le stockage partagé, les régions, la capacité de verrouillage, le plan de reprise et la manière de révoquer. Pour une application plus large, le test de réversibilité cloud et SaaS aide aussi à vérifier qu’une clé, une file ou un stockage de session ne reste pas enfermé dans un fournisseur invisible.

Comment migrer les installations existantes sans attendre le marchand ?

Shopify permet d’échanger directement un jeton hors ligne non expirant encore actif contre une paire expirante. Cette opération ne demande ni session utilisateur ni réinstallation. Elle convient aux applications en arrière-plan et aux boutiques dont les utilisateurs ouvrent rarement l’interface.

Cette facilité rend l’ordre des opérations décisif :

  1. déployer d’abord le code capable de lire, renouveler et stocker la nouvelle paire ;
  2. inventorier les boutiques et les workers qui utilisent réellement l’ancien jeton ;
  3. migrer un petit lot représentatif ;
  4. exécuter les flux critiques et les scénarios de reprise ;
  5. observer les journaux avant d’élargir ;
  6. migrer les installations restantes avec une progression et une condition d’arrêt ;
  7. rechercher les usages résiduels du jeton ancien avant de déclarer la fin.

L’échange direct invalide immédiatement l’ancien jeton pour les appels GraphQL Admin API. Il ne faut donc pas compter sur un retour au jeton permanent après la migration. Le retour arrière porte sur la version du code, le routage des workers ou l’arrêt du lot suivant, pas sur la restauration de l’ancien secret.

Si la réponse initiale de migration est perdue, Shopify autorise une répétition avec l’ancien jeton et les identifiants valides pendant une fenêtre de sept jours. Cette reprise retourne la même paire lorsqu’elle est encore admissible. Elle cesse notamment après l’utilisation du jeton de renouvellement issu de cette paire ou après une acquisition plus récente pour la boutique. Le stockage de l’état de migration doit donc distinguer « requête non partie », « réponse inconnue », « paire enregistrée » et « paire déjà utilisée ».

Huit scénarios de recette bloquants

La validation doit provoquer les pannes que la rotation rend possibles. Un appel nominal réussi juste après le déploiement ne prouve pas la continuité.

  1. Installation active nominale. Migrer une boutique pilote, appeler l’Admin API, laisser le mécanisme renouveler, puis vérifier que le flux métier reste complet et attribué à la même installation.
  2. Boutique inactive et traitement en arrière-plan. Migrer sans session marchand, puis exécuter un webhook, une tâche planifiée ou une action Flow. Aucun écran ne doit être nécessaire pour reprendre.
  3. Réponse de migration perdue. Simuler la coupure après acceptation par Shopify mais avant l’écriture locale. Rejouer la récupération autorisée, enregistrer la paire une seule fois et empêcher une double bascule.
  4. Deux workers concurrents. Déclencher un renouvellement simultané depuis deux processus. Un seul propriétaire doit effectuer l’échange ; les autres relisent l’état cohérent au lieu de conserver une paire concurrente.
  5. Échec d’écriture après renouvellement. Refuser temporairement la transaction de stockage. Vérifier la reprise avec le jeton précédent encore admissible, puis l’écriture atomique de la paire complète.
  6. Jeton de renouvellement perdu ou retiré. Tester la récupération prévue : accès applicatif signé lorsque l’application y est préparée, ou nouvelle autorisation lorsque ce secours n’existe pas. L’échec doit devenir une alerte exploitable, pas une boucle silencieuse.
  7. Origine réseau non autorisée. Après activation de la liste d’adresses IP, appeler l’Admin API depuis une adresse attendue puis depuis une adresse extérieure. Le second appel doit être refusé sans bloquer les workers légitimes ni le plan de secours.
  8. Ancien worker encore actif. Relancer une tâche rare, une file ancienne ou une région secondaire qui conserve le jeton permanent. Les journaux doivent l’identifier avant la fin du pilote et empêcher la déclaration de conformité.

Ajoutez deux contrôles transverses. Un HTTP 403 peut aussi signaler un scope absent : le traitement doit examiner le message au lieu de relancer aveuglément toute l’autorisation. Puis rejouez la désinstallation, la révocation et la rotation de clé afin de vérifier que l’accès disparaît sur chaque chemin prévu.

Pour chaque scénario, conservez la boutique de test, la version du code, le type de jeton, l’horodatage, le worker, le résultat API, l’effet métier et la décision. N’enregistrez jamais les secrets eux-mêmes dans les journaux ou les captures.

Les restrictions IP et la déclaration réseau suffisent-elles ?

Non. La liste d’adresses IP réduit l’endroit depuis lequel un jeton valide peut appeler l’Admin API. Elle rend un jeton volé moins utile hors des serveurs déclarés. Elle ne corrige ni un serveur compromis, ni un scope trop large, ni une autorisation appliquée au mauvais marchand.

La restriction demande aussi un inventaire réel des sorties réseau : production, workers, régions, reprise, tâches ponctuelles et éventuels fournisseurs. Une adresse dynamique oubliée peut transformer une protection en interruption. Activez-la d’abord sur un périmètre observable, vérifiez le refus depuis l’extérieur, puis documentez le changement nécessaire lorsqu’une infrastructure évolue.

Le bloc [network_access] de shopify.app.toml déclare les serveurs et sites utilisés par l’application. Shopify indique s’en servir pour repérer des requêtes que l’application n’a pas initiées et pour traiter les destinations vers lesquelles elle envoie un client. Cette déclaration est un inventaire vérifiable ; elle ne remplace pas les règles réseau, le contrôle des sorties ni l’examen des dépendances. Pour qualifier les échéances et vérifier cet inventaire sur une boutique isolée, utilisez la recette de déclaration des accès réseau Shopify.

Une sécurité utile combine donc : durée courte, stockage protégé, scopes minimaux, origine réseau attendue, journaux sans secret, révocation testée et responsable capable d’agir. Le guide sur les accès distants d’un logiciel métier applique la même logique aux personnes et prestataires ; ici, l’identité appartient à une application et la recette doit couvrir les processus automatiques.

Comment prouver que la migration est terminée ?

La possession d’un jeton expirant ne prouve pas que tous les appels utilisent la nouvelle voie. Shopify explique que son signal repose sur les jetons réellement présentés à l’Admin API et que l’historique récent peut rester visible après la migration. Les vieux workers, tâches rares, files retardées et boutiques rouvertes sont donc les meilleurs tests de fin.

Le dossier de sortie doit contenir au minimum :

  • la liste des installations dans le périmètre et leur état de migration ;
  • le type de jeton cible et la méthode d’acquisition choisie ;
  • le propriétaire du renouvellement ou de la signature ;
  • la preuve de stockage atomique et de concurrence contrôlée ;
  • le résultat des huit scénarios ;
  • les usages résiduels observés et leur correction ;
  • la procédure de récupération, de révocation et de rotation des clés ;
  • la date de la prochaine revue et le responsable.

Reliez ensuite cette preuve à l’effet métier : commandes synchronisées, stocks cohérents, contenu actualisé, traitement sans doublon et alertes attribuées. La supervision d’une application Shopify fournit les signaux, seuils et procédures de réconciliation nécessaires après la migration.

Par quoi commencer cette semaine ?

Choisissez une seule application publique et un seul flux dont l’arrêt serait visible : création de commande, stock, prix, traduction ou traitement en arrière-plan. Confirmez le type de jeton réellement utilisé, puis identifiez le service qui peut en devenir propriétaire.

Remplissez la matrice pour trois installations : une active, une rarement ouverte et une qui exécute un traitement de fond. Déployez la capacité de rotation avant l’échange du premier jeton. Rejouez ensuite trois scénarios prioritaires : renouvellement concurrent, réponse perdue et ancien worker encore actif.

Si l’application ne peut pas enregistrer une paire atomiquement ou coordonner ses workers, ne lancez pas une migration massive. Corrigez d’abord cette frontière. Si la rotation fonctionne mais que le secours dépend d’une clé non gouvernée, attribuez la rotation et la révocation avant de l’activer. Si les preuves sont solides, élargissez par lots avec une condition d’arrêt explicite.

Anakyos conçoit et fait évoluer des plateformes e-commerce et leurs intégrations en reliant identité, flux, exploitation et résultat métier. Un premier cadrage peut rester limité à l’inventaire, la matrice, un flux critique et trois scénarios avant de généraliser la migration.

Sources officielles

La migration est terminée lorsque l’application sait renouveler, perdre, récupérer et retirer un jeton sans perdre le flux métier ni rouvrir un accès permanent.

Écrit et relu par

Équipe AnakyosThomas et Bastien croisent architecture logicielle, stratégie produit, design et opérations pour transformer des sujets complexes en produits numériques clairs et durables.