Shopify GraphQL Admin API: Scopes und Daten sicher Schritt für Schritt nutzen

Die GraphQL Admin API ist für Shopify-Apps ein zentraler Weg, Shopdaten zu lesen und Änderungen vorzunehmen. Der sichere Einstieg besteht nicht darin, möglichst viele Berechtigungen anzufordern. Entscheidend ist, für jede Funktion den tatsächlichen Datenbedarf zu bestimmen und die Authentifizierung dem offiziellen Shopify-Template zu überlassen.

Die GraphQL-Admin-API-Referenz dokumentiert das aktuelle Schema und zeigt Beispiele für React Router. Shopify versioniert die API regelmäßig. Verwende für ein Projekt die Version, die in seiner Shopify-Konfiguration festgelegt und für den geplanten Release unterstützt wird, und prüfe die Referenz für genau diese Version.

Schritt 1: Datenbedarf nach Funktion aufschreiben

Erstelle vor der Konfiguration eine einfache Tabelle:

App-Funktion	Benötigte Daten oder Aktion	Möglicher Scope
Produktliste anzeigen	Produkte lesen	read_products
Produktdaten aktualisieren	Produkte ändern	write_products

Das sind Beispiele, keine pauschale Berechtigungsempfehlung. Prüfe im Shopify-Verzeichnis der Zugriffsscopes sowie in der Dokumentation des konkreten API-Felds, welcher Zugriff tatsächlich benötigt wird. Bei Kunden- oder Bestelldaten können zusätzliche Anforderungen für geschützte Kundendaten gelten.

Schritt 2: Nur notwendige Scopes konfigurieren

In einer CLI-App werden Scopes im App-Konfigurationsfile festgelegt. Eine Konfiguration kann zum Beispiel so aussehen:

[access_scopes]
scopes = "read_products"

Ergänze einen Scope erst dann, wenn eine konkrete Funktion ihn braucht. Fordert eine App unnötig breite Rechte, wird die Installation für Händler schwerer nachvollziehbar und die Sicherheitsfläche größer. Shopify erklärt die Einrichtung und Aktualisierung in der Dokumentation zu App-Konfiguration und Scopes.

Wenn sich angeforderte Scopes ändern, berücksichtige den dafür vorgesehenen Installations- und Freigabeablauf. Teste die App nach einer Änderung erneut im Development Store; ein lokaler Code-Change allein beweist noch nicht, dass der Shop den neuen Zugriff autorisiert hat.

Verwendest du Shopify CLI, müssen geänderte Scopes für die App-Konfiguration bereitgestellt werden. Im Development-Modus folgst du dem durch shopify app dev angezeigten Freigabe- und Aktualisierungsablauf; vor einem Release deployest du die App-Konfiguration mit:

shopify app deploy

Prüfe anschließend die tatsächlich angeforderten und genehmigten Berechtigungen im Development Store.

Schritt 3: Eingehende Admin-Anfrage authentifizieren

Bei einer serverseitigen React-Router-App authentifiziert das Shopify-Template die Admin-Anfrage. Danach verwendest du den von Shopify bereitgestellten admin-Client. Laut Authentifizierungsdokumentation sollte die App für die meisten Fälle den durch Shopify CLI und offizielle Templates bereitgestellten Ablauf nutzen, statt OAuth von Hand zu implementieren.

Ein minimales Lese-Beispiel nach dem offiziellen React-Router-Muster:

import { authenticate } from "../shopify.server";

export async function loader({ request }: { request: Request }) {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `query { shop { name } }`,
  );
  const result = await response.json();

  return result;
}

Passe Importpfad, Typen und Rückgabe an die konkrete Version deines generierten Projekts an. In einer echten Route solltest du API-Fehler prüfen und nur die Daten zurückgeben, die die UI benötigt. Gib niemals Tokens an den Browser weiter und speichere sie nicht im Quellcode.

Schritt 4: Query klein und zielgerichtet halten

Starte mit wenigen Feldern. Eine Abfrage, die nur die erste kleine Produktseite und genau die benötigten Werte lädt, ist leichter zu testen als ein großer Datenabruf, der den vollständigen Katalog auf einmal anfordert.

query ProductList {
  products(first: 10) {
    nodes {
      id
      title
      status
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Wenn es mehr Datensätze gibt, verwende pageInfo und den Cursor für die nächste Seite. So bleibt die Oberfläche kontrollierbar, und die App kann ihren Datenabruf an die tatsächliche Nutzung anpassen. Prüfe in der API-Referenz die benötigten Scopes, Argumente und etwaige Versionshinweise für jedes Feld.

Schritt 5: Änderungen über Mutations absichern

Eine Mutation verändert Shopdaten. Zeige sie deshalb nicht als reine Leseoperation an: Prüfe Eingaben, bestätige die fachliche Aktion und werte die von Shopify zurückgegebenen Fehlerfelder aus. Berücksichtige außerdem, ob Händler die Änderung wiederholen oder zurücknehmen können.

Zum Testen gehört nicht nur der erfolgreiche Fall:

1. Installiere die App auf einem Development Store.
2. Prüfe, dass die freigegebenen Scopes der App-Konfiguration entsprechen.
3. Teste eine gültige Abfrage und eine erlaubte Änderung.
4. Entferne testweise eine Berechtigung beziehungsweise nutze einen Fall ohne Zugriff.
5. Stelle sicher, dass die App verständlich reagiert und keine vertraulichen Details offenlegt.

Schritt 6: Datenzugriff vor dem Release überprüfen

Kontrolliere vor jeder Veröffentlichung, ob neue Features weitere Scopes benötigen, ob personenbezogene Daten verarbeitet werden und ob die App dafür die erforderlichen Genehmigungen besitzt. Öffentliche Apps müssen zusätzliche Shopify-Vorgaben für geschützte Kundendaten einhalten. Richte Zugriffsrechte nicht nach dem Motto „vielleicht später“, sondern nach dem tatsächlich verfügbaren Feature-Umfang aus.

Offizielle Shopify-Quellen

• GraphQL Admin API
• Über App-Authentifizierung
• Zugriffsscopes verwalten
• API-Zugriffsscopes
• GraphQL Admin API mit React Router
• Protected Customer Data

Die Admin-API ist versionsgebunden. Prüfe Schema, Scope-Anforderungen und Deprecations immer für die API-Version deiner App.