Authentifizierung und API-Schlüssel

Sowohl die REST-API als auch der MCP-Server verwenden dieselbe Anmeldeinformation: einen API-Schlüssel, der auf der Developer-Seite innerhalb der App erstellt wird.

Basis-URL

Alle Anfragen gehen an:

text

https://shopify.workflow-transactional-email.app

Jeder unten aufgeführte Endpunkt ist relativ zu diesem Host, sodass der vollständige Pfad für den Index https://shopify.workflow-transactional-email.app/api/v1 lautet.

Einen Schlüssel erstellen

Öffnen Sie Developer in der App, wählen Sie eine Zugriffsebene aus und erstellen Sie den Schlüssel. Der vollständige Wert wird einmalig, bei der Erstellung angezeigt. Kopieren Sie ihn in diesem Moment und speichern Sie ihn in Ihrem Passwort-Manager oder Secret-Store - er kann danach nicht mehr abgerufen werden, da nur ein SHA-256-Hash davon gespeichert wird.

Schlüssel beginnen immer mit fak_, was sie in einem Secret-Scanner leicht erkennbar macht.

Senden Sie ihn als Bearer-Token:

vbnet

GET /api/v1/me HTTP/1.1
Host: shopify.workflow-transactional-email.app
Authorization: Bearer fak_your_key_here

GET /api/v1/me ist die schnellste Möglichkeit, um zu prüfen, ob ein Schlüssel funktioniert, und um zu sehen, welche Ebene er besitzt.

Zugriffsebenen

Die Ebenen sind geordnet und kumulativ: Jede Ebene enthält alles, was darunter liegt.

Ebene	Was sie hinzufügt
Nur Lesen	E-Mail-Layouts, E-Mail-Absender, Secret-Namen, hochgeladene Dateien, HTTP-Anfragen, Verlauf und Statistiken lesen
Lesen & Schreiben	HTTP-Anfragen erstellen, bearbeiten und löschen sowie nicht verwendete hochgeladene Dateien löschen
Lesen, Schreiben & Ausführen	Eine HTTP-Anfrage gegen ihr tatsächliches Ziel ausführen

Beachten Sie, wie eingeschränkt die beiden oberen Ebenen sind. Alles rund um E-Mail ist lesbar, aber auf keiner Ebene beschreibbar - siehe unten.

Was ein Schreib-Schlüssel ändern kann und was nicht

Kann: HTTP-Anfragen erstellen, bearbeiten, löschen und ausführen sowie hochgeladene Dateien löschen, auf die nichts verweist.

Kann nicht: irgendetwas anfassen, das bestimmt, was Ihre Kunden erhalten. E-Mail-Layouts, E-Mail-Absender und Secrets haben auf keiner Zugriffsebene einen Schreib-Endpunkt, und es gibt überhaupt keinen Endpunkt zum Versenden von E-Mails. E-Mails werden versendet, wenn Ihr Shopify-Flow-Workflow die Aktion „Transaktions-E-Mail senden“ ausführt; die API zeichnet dies anschließend nur auf und meldet es.

Das Löschen von Dateien wird ebenfalls verweigert, solange noch ein Layout oder eine Vorlage die Datei verwendet, sodass ein Schreib-Schlüssel keine aktive E-Mail durch Entfernen ihres Logos beschädigen kann.

Wenn Sie ein Layout ändern oder einen Absender verbinden müssen, tun Sie dies in der App.

Warum „Ausführen“ eine eigene Ebene ist

Das Ausführen einer HTTP-Anfrage sendet eine echte Anfrage an ein echtes Drittsystem. Indem dies hinter einer eigenen Ebene verborgen wird, kann ein Schlüssel, den Sie einem Skript - oder einem KI-Assistenten - zum Lesen und Bearbeiten der Konfiguration übergeben, keine Anfragen an Ihre Live-Integrationen auslösen.

Vergeben Sie standardmäßig Lese-Schlüssel. Fügen Sie „Schreiben“ oder „Ausführen“ nur hinzu, wenn eine bestimmte Aufgabe dies erfordert.

Einen Schlüssel widerrufen

Löschen Sie den Schlüssel auf der Developer-Seite. Der Widerruf wird mit der nächsten Anfrage wirksam - es gibt keinen Cache, auf den gewartet werden muss.

Widerrufen und neu ausstellen, wenn ein Schlüssel in ein Repository eingecheckt, in ein gemeinsam genutztes Dokument eingefügt oder an einen Auftragnehmer weitergegeben wurde, der ihn nicht mehr benötigt.

Gute Gewohnheiten

Verweisen Sie in Ihren HTTP-Anfragen auf Anmeldeinformationen als {{ secrets.KEY }}, anstatt sie in einen Header oder Body einzufügen. Wörtlich angegebene Anmeldeinformationen werden in API-Antworten maskiert, aber der Verweis auf ein Secret ist besser.
Verwenden Sie einen Schlüssel pro Verbraucher, sodass Sie eine einzelne Integration widerrufen können, ohne die anderen zu beeinträchtigen.
Halten Sie Ausführungs-Schlüssel von Entwickler-Laptops und aus KI-Assistenten-Konfigurationen fern, es sei denn, Sie möchten ausdrücklich, dass der Assistent Live-Anfragen auslösen kann.