Logo

Was hat sich am Refresh-Mechanismus des Shopify Offline Tokens geändert?

avatar jayce 03 Sep 2026

Wenn Sie kürzlich den Autorisierungscode Ihrer Shopify-App verwaltet haben, ist dieses Update einen genaueren Blick wert.

Am 10. Dezember 2025 hat Shopify im Entwickler-Änderungsprotokoll klargestellt: Der Offline-Zugriffstoken unterstützt jetzt das Verfallen und die Erneuerung. Am 20. März 2026 fügte ein weiteres Änderungsprotokoll eine noch strengere Anforderung hinzu: Ab dem 1. April 2026 müssen neu erstellte öffentliche Apps, die die Admin-API aufrufen, einen ablaufenden Offline-Zugriffstoken verwenden.

Dies ist keine Änderung, die sofort alle alten Anwendungen unterbricht. Bereits bestehende öffentliche Apps, benutzerdefinierte Apps und von Händlern im Backend erstellte Apps fallen nicht unter diese Regel vom 1. April. Wenn Sie jedoch eine neue App entwickeln oder in diesem Jahr eine neue öffentliche App starten, ist es am besten, diese Erneuerungslogik von Anfang an zu integrieren.

Die Annahme, dass man nach der Installation einfach weitermachen kann, ist verschwunden

Viele Backend-Aufgaben von Shopify-Apps sind auf den Offline-Token angewiesen. Zum Beispiel das Synchronisieren von Bestellungen, das Verarbeiten von Webhooks, das regelmäßige Abrufen von Produkten und das Erstellen von Berichten für den Shop. Wenn der Händler nicht online ist, muss die App auch die Admin-API aufrufen können, weshalb der Offline-Token immer die Standardwahl war.

Die gängige Handhabung im alten Code war einfach: Der Händler erhält beim Installieren den Token und speichert ihn in der Datenbank; bei jedem weiteren Aufruf der Admin-API wird dieser in den X-Shopify-Access-Token eingefügt. Solange der Händler die App nicht deinstalliert, geht das Team normalerweise davon aus, dass dieser Token weiterhin gültig ist.

Der neue ablaufende Offline-Token hat diese Annahme jedoch aufgehoben. Die offizielle Dokumentation besagt jetzt klar: Die Gültigkeitsdauer des ablaufenden Offline-Zugriffstokens beträgt 1 Stunde, und die expires_in-Angabe in der Antwort beträgt 3600. Gleichzeitig wird ein refresh_token zurückgegeben, mit dem die App einen neuen Zugriffstoken anfordern kann, ohne den Händler zu stören.

Zum Beispiel hat ein unabhängiger Shop für Haustierbedarf etwa 200 SKUs und führt alle 15 Minuten eine Bestandsaktualisierung durch. Früher musste die Synchronisierungsaufgabe nur den Offline-Token aus der Shop-Datenbank lesen. Jetzt muss sie mindestens zwei weitere Felder überprüfen: Wann läuft der Zugriffstoken ab und ist der Refresh-Token noch gültig? Andernfalls könnte die Synchronisierungsaufgabe um Mitternacht beim ersten Auftreten eines 401-Fehlers die gesamte Bestandsaktualisierung für die Nacht stoppen.

Erneuerung ist nicht der gesamte Installationsprozess

Ein entscheidender Punkt dieser Änderung von Shopify ist, dass die Erneuerung am Token-Endpunkt erfolgt und der Händler nicht erneut die Autorisierung bestätigen muss.

Der in der offiziellen Dokumentation angegebene OAuth-Token-Endpunkt lautet:

POST https://{shop}.myshopify.com/admin/oauth/access_token

Wenn Sie den Token-Austausch verwenden, können Sie beim Abrufen des Offline-Tokens requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token hinzufügen und expiring auf 1 setzen. Wenn Sie den Autorisierungscode-Grant verwenden, fordern Sie beim Austausch des Codes ebenfalls einen ablaufenden Offline-Token an, indem Sie expiring=1 angeben.

In der Antwort müssen Sie nicht nur den access_token speichern. Sie sollten auch diese Informationen speichern:

• expires_in: die verbleibenden Sekunden des aktuellen Zugriffstokens, offiziell sind das 3600 Sekunden

• refresh_token: der Token, der für die nächste Servererneuerung benötigt wird

• refresh_token_expires_in: die anfängliche Gültigkeitsdauer des Refresh-Tokens, offiziell sind das 7776000 Sekunden, also 90 Tage

Hier sollten Sie die 3600 nicht fest codieren. Die offizielle Dokumentation weist auch darauf hin, dass die App die expires_in-Angabe in der Antwort lesen sollte und nicht davon ausgehen sollte, dass die Gültigkeitsdauer immer gleich bleibt.

Die größte Falle ist die gleichzeitige Erneuerung

Die Erneuerungslogik sieht einfach aus, aber die eigentlichen Probleme treten bei der Rotation auf.

Shopify dokumentiert dies sehr detailliert: Bei jeder Erneuerung werden ein neuer Zugriffstoken und ein neuer Refresh-Token zurückgegeben. Die App muss beide speichern und beim nächsten Erneuern den neuen Refresh-Token verwenden.

Der alte Refresh-Token wird nicht sofort ungültig, wenn Shopify einen neuen Token ausgibt. Er wird zu dem frühesten Zeitpunkt ungültig, der unter mehreren Bedingungen auftritt: Die App hat den neuen Refresh-Token verwendet; die App hat erneut über den Token-Austausch oder den Autorisierungscode-Grant einen neuen Token angefordert; der alte Refresh-Token wurde zum ersten Mal zur Erneuerung verwendet und ist seitdem 30 Tage vergangen; oder seine ursprüngliche Gültigkeit von 90 Tagen ist abgelaufen.

Diese Regel hat direkte Auswirkungen auf die Implementierung. Angenommen, Ihr Webhook-Worker und Ihre geplante Aufgabe stellen gleichzeitig fest, dass der Token bald abläuft, und beide Prozesse versuchen gleichzeitig zu erneuern. Beide schreiben das Ergebnis in die Datenbank, und der zuletzt geschriebene überschreibt den vorherigen. Welcher Refresh-Token beim nächsten Aufruf verwendet wird, könnte von einem Wettlauf abhängen.

Eine stabilere Vorgehensweise besteht darin, auf der Ebene des Shops eine Sperre zu setzen oder in der Datenbank eine bedingte Aktualisierung vorzunehmen: Nur wenn der Refresh-Token in der aktuellen Aufzeichnung der ist, den Sie gerade gelesen haben, darf der neue Token geschrieben werden. Bei einem Erneuerungsfehler sollten Sie die Aufzeichnung erneut lesen und den Händler nicht sofort zurück zur OAuth-Authentifizierung schicken.

401 ist nicht der einzige Auslöser

Nur bei Erhalt eines 401-Fehlers zu erneuern, kann einige Anfragen retten, aber Hintergrundaufgaben werden einen zusätzlichen Fehler haben. Bei Aufgaben wie Webhooks, die eine Wiederholung haben, ist das in Ordnung, aber bei manuell ausgelösten Exporten oder Massenaktualisierungen wird die Erfahrung rauer sein.

Die offizielle Empfehlung ist, einige Minuten im Voraus zu erneuern und bei Erhalt eines 401-Fehlers einen weiteren Erneuerungsversuch zu unternehmen. In der Implementierung können Sie für jeden Shop expires_at speichern und vor der Anfrage überprüfen, ob die Gültigkeit bald abläuft. Wenn die Gültigkeit in weniger als 5 Minuten abläuft, sollten Sie zuerst erneuern, bevor Sie die Admin-API anrufen.

Ein Erneuerungsfehler sollte ebenfalls separat protokolliert werden. Die Gründe könnten abgelaufene Refresh-Tokens, wechselnde Client-Secrets, Deinstallationen durch den Händler oder Ihre Speicherung, die den neuen Refresh-Token nicht korrekt speichert, sein. Diese führen letztendlich alle zu einem 401-Fehler, aber die Handhabung ist unterschiedlich.

Alte Anwendungen können sich jetzt etwas Zeit lassen, aber vermeiden Sie es, technische Schulden anzuhäufen

Die Anforderung vom 1. April 2026 betrifft nur neu erstellte öffentliche Apps. Shopify hat auch klargestellt, dass öffentliche Apps, die vor dem 1. April erstellt wurden, vorerst nicht betroffen sind.

Allerdings gibt es in der Dokumentation zu Zugriffstokens eine weitere Zeitlinie: Öffentliche Apps müssen bis zum 1. Januar 2027 ablaufende Offline-Zugriffstokens verwenden, um die Admin-API anzufordern. Benutzerdefinierte Apps und von Händlern erstellte Apps fallen nicht in diesen Bereich.

Daher müssen alte Anwendungen nicht sofort migriert werden, aber wenn Sie bereits an der Autorisierungsschicht arbeiten, ist es am besten, die Datenbankstruktur und den Erneuerungsweg entsprechend vorzubereiten. Zumindest sollten Sie die Anmerkung “offline token läuft niemals ab” entfernen und in den Hintergrundaufgaben 401-Fehler nicht mehr pauschal als Deinstallation des Händlers klassifizieren.

Ich habe noch nicht versucht, die interne Implementierung der neuesten Bibliotheken in einem echten Shopify-Vorlagenprojekt zeilenweise zu überprüfen. Offiziell heißt es, dass, wenn Sie Shopify-App-Vorlagen und -Bibliotheken verwenden, dieser Teil bereits gut behandelt wurde. Bei selbstgebauten OAuth, alten Rails-Apps oder Projekten, die die Autorisierungsschicht der Vorlage geändert haben, sollten Sie jedoch selbst den Token-Speicher und den Erneuerungsweg überprüfen.

Diese Punkte können Sie zuerst ändern

Sie müssen nicht sofort das gesamte Autorisierungssystem neu schreiben. Überprüfen Sie zuerst vier Punkte:

• Gibt es in der Datenbank einen Platz, um refresh_token, expires_at und refresh_token_expires_at zu speichern?

• Kann in der Admin-API-Anfrageverpackung vor der Anfrage die Ablaufzeit überprüft werden?

• Werden Hintergrundaufgaben und Webhook-Worker gleichzeitig den Token für denselben Shop erneuern?

• Können Sie in den 401-Protokollen zwischen abgelaufenen Tokens, unzureichenden Berechtigungen und Deinstallationen der App unterscheiden?

Wenn die App noch nicht ablaufende Offline-Tokens verwendet, kann die neue Version zunächst bei der Installation oder dem Token-Austausch expiring=1 hinzufügen und die Erneuerungslogik in einen einheitlichen API-Client integrieren. So müssen die Synchronisierung von Produkten, Bestellungen und Berichten nicht jeweils eine eigene Erneuerungscode schreiben.

Diese Änderung ist nicht extravagant, aber sie ähnelt Shopify, das die App-Autorisierung in Richtung eines standardisierten OAuth-Verhaltens verschiebt. Hintergrundaufgaben können weiterhin ausgeführt werden, aber in Zukunft können sie sich nicht mehr auf einen permanenten Token verlassen, um den gesamten Lebenszyklus zu unterstützen.

Offizielle Quellen:

• 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

Book Free 30-Min Call