Authenticatie en API-sleutels

Zowel de REST API als de MCP-server maken gebruik van dezelfde inloggegevens: een API-sleutel die is aangemaakt op de pagina ‘Ontwikkelaar’ binnen de app.

Basis-URL

Alle verzoeken dient u te richten aan:

text

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

Elk onderstaand eindpunt is relatief ten opzichte van die host, zodat het volledige pad naar de index https://shopify.workflow-transactional-email.app/api/v1 is.

Een sleutel aanmaken

Open Developer in de app, kies een toegangsniveau en maak de sleutel aan. De volledige waarde wordt eenmalig weergegeven**, op het moment van aanmaken**. Kopieer deze vervolgens en sla hem op in uw wachtwoordbeheerder of geheime opslagplaats - hij kan achteraf niet meer worden opgehaald, omdat er alleen een SHA-256-hash van wordt bewaard.

Sleutels beginnen altijd met fak_, waardoor ze gemakkelijk te herkennen zijn in een geheimscanner.

Verzend het als een ‘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 is de snelste manier om te controleren of een sleutel werkt en om te zien welk beveiligingsniveau deze biedt.

Toegangsniveaus

De niveaus zijn hiërarchisch en cumulatief: elk niveau omvat alle onderliggende niveaus.

Niveau	Wat het toevoegt
Alleen-lezen	E-mailopmaak, afzenders van e-mails, geheime namen, geüploade bestanden, HTTP-verzoeken, geschiedenis en statistieken lezen
Lezen en schrijven	HTTP-verzoeken aanmaken, bewerken en verwijderen, en ongebruikte geüploade bestanden verwijderen
Lezen, schrijven en uitvoeren	Voer een HTTP-verzoek uit naar het daadwerkelijke doel

Let erop hoe beperkt de bovenste twee niveaus zijn. Alles wat met e-mail te maken heeft, is leesbaar, maar op geen enkel niveau is het mogelijk om gegevens te schrijven - zie hieronder.

Wat een schrijftoets wel en niet kan wijzigen

Kan: HTTP-verzoeken aanmaken, bewerken, verwijderen en uitvoeren, en geüploade bestanden verwijderen waarnaar nergens wordt verwezen.

Het is niet mogelijk om wijzigingen aan te brengen in zaken die bepalen wat uw klanten ontvangen. E-maillay-outs, e-mailafzenders en geheimen beschikken op geen enkel toegangsniveau over een schrijf-eindpunt, en er is helemaal geen eindpunt voor het verzenden van e-mails. E-mails worden verzonden wanneer uw Shopify Flow-workflow de actie „Transactionele e-mail verzenden” uitvoert; de API registreert en rapporteert dit pas achteraf.

Het verwijderen van een bestand wordt eveneens geweigerd zolang een lay-out of voorinstelling nog gebruikmaakt van het bestand; een schrijftoets kan dus geen actieve e-mail beschadigen door het logo ervan te verwijderen.

Als u een lay-out wilt wijzigen of een afzender wilt koppelen, kunt u dit in de app doen.

Waarom ‘execute’ apart staat

Het uitvoeren van een HTTP-verzoek leidt tot het verzenden van een daadwerkelijk verzoek naar een daadwerkelijk systeem van een derde partij. Door dit op een apart niveau te houden, wordt voorkomen dat een sleutel die u aan een script - of aan een AI-assistent - verstrekt voor het lezen en bewerken van de configuratie, verzoeken kan versturen naar uw live-integraties.

Verleen standaard leesrechten. Voeg schrijf- of uitvoerrechten alleen toe wanneer een specifieke taak deze nodig heeft.

Een sleutel intrekken

Verwijder de sleutel op de pagina ‘Ontwikkelaar’. De intrekking wordt van kracht bij het volgende verzoek - er is geen cache waar u op hoeft te wachten.

Trek de sleutel in en geef deze opnieuw uit indien deze in een repository is opgeslagen, in een gedeeld document is geplakt of aan een contractant is verstrekt die deze niet langer nodig heeft.

Goede gewoonten

Vermeld uw inloggegevens als {{ secrets.KEY }} in uw HTTP-verzoeken, in plaats van deze in een header of body te plakken. Letterlijke inloggegevens worden in API-antwoorden gemaskeerd, maar het is beter om naar een geheim te verwijzen.
Gebruik één sleutel per klant, zodat u één integratie kunt intrekken zonder dat dit gevolgen heeft voor de overige integraties.
Zorg ervoor dat uitvoeringssleutels niet op de laptops van ontwikkelaars staan en niet in de configuraties van AI-assistenten worden opgenomen, tenzij u specifiek wilt dat de assistent live-verzoeken kan versturen.