Authentification et clés API

L'API REST et le serveur MCP utilisent tous deux les mêmes identifiants : une clé API créée sur la page « Développeur » de l'application.

URL de base

Toutes les demandes doivent être adressées à :

text

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

Chaque point de terminaison ci-dessous est relatif à cet hôte ; le chemin d'accès complet vers l'index est donc https://shopify.workflow-transactional-email.app/api/v1.

Création d'une clé

Ouvrez Developer dans l'application, choisissez un niveau d'accès, puis créez la clé. La valeur complète s'affiche une seule fois, lors de la création. Copiez-la alors et enregistrez-la dans votre gestionnaire de mots de passe ou votre espace de stockage de secrets : elle ne pourra plus être récupérée par la suite, car seul son hachage SHA-256 est conservé.

Les clés commencent toujours par fak_, ce qui permet de les repérer facilement dans un scanner de mots de passe.

Envoyez-le sous forme de jeton au porteur :

vbnet

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

GET /api/v1/me C'est le moyen le plus rapide de vérifier si une clé fonctionne et de déterminer le niveau auquel elle correspond.

Niveaux d'accès

Les niveaux sont hiérarchisés et cumulatifs : chacun d'entre eux englobe tous ceux qui lui sont subordonnés.

Niveau	Ce que cela apporte
Lecture seule	Consultez la mise en page des e-mails, les expéditeurs, les noms cachés, les fichiers téléchargés, les requêtes HTTP, l'historique et les statistiques
Lecture et écriture	Créer, modifier et supprimer des requêtes HTTP, et supprimer les fichiers téléchargés qui ne sont plus utilisés
Lire, écrire et exécuter	Envoyez une requête HTTP vers sa cible réelle

Remarquez à quel point les deux niveaux supérieurs sont restreints. Tout ce qui concerne les e-mails est accessible en lecture, mais rien n'est modifiable, à aucun niveau - voir ci-dessous.

Ce qu'une clé d'écriture peut et ne peut pas modifier

Peut : créer, modifier, supprimer et exécuter des requêtes HTTP, ainsi que supprimer les fichiers téléchargés auxquels rien ne fait référence.

Impossible : ne modifiez en aucun cas les éléments qui déterminent ce que vos clients reçoivent. Les mises en page des e-mails, les expéditeurs et les secrets ne disposent d'aucun point de terminaison en écriture, quel que soit le niveau d'accès, et il n'existe tout simplement aucun point de terminaison permettant d'envoyer des e-mails. Les e-mails sont envoyés lorsque votre workflow Shopify Flow exécute l'action « Envoyer un e-mail transactionnel » ; l'API se contente ensuite de l'enregistrer et d'en rendre compte.

La suppression d'un fichier est également refusée tant qu'une mise en page ou un préréglage utilise encore ce fichier ; ainsi, une touche d'écriture ne peut pas endommager un e-mail en ligne en supprimant son logo.

Si vous devez modifier une mise en page ou associer un expéditeur, effectuez ces opérations dans l'application.

Pourquoi la fonction « exécuter » est-elle distincte ?

L'exécution d'une requête HTTP envoie une véritable requête à un véritable système tiers. En isolant cette opération au sein de son propre niveau, vous vous assurez qu'une clé que vous confiez à un script - ou à un assistant IA - pour lire et modifier la configuration ne puisse pas déclencher de requêtes vers vos intégrations en production.

Attribuez par défaut des droits de lecture. N'ajoutez les droits d'écriture ou d'exécution que lorsqu'une tâche spécifique en a besoin.

Les secrets ne sont jamais lisibles, à aucun niveau

Les valeurs secrètes, les noms d'utilisateur et mots de passe SMTP, ainsi que les jetons de boîte aux lettres connectée ne peuvent être récupérés par aucune de ces deux interfaces. Ni à l'aide d'une clé d'écriture, ni d'une clé d'exécution, ni via MCP. Aucun point de terminaison ni aucun outil ne permet de les récupérer.

Vous disposez à la place de drapeaux et de noms secrets tels que hasValue, hasUsername et hasPassword, ce qui suffit pour qu’un assistant puisse faire référence à {{ secrets.stripeApiKey }} sans jamais voir la valeur. Vous pouvez toujours définir une nouvelle valeur ; vous ne pouvez jamais récupérer une ancienne.

Conséquence concrète : la fuite d'une clé de lecture expose votre configuration, et non vos identifiants.

Révocation d'une clé

Supprimez la clé sur la page « Développeur ». La révocation prend effet dès la prochaine requête : il n'y a pas de cache à vider.

Répétez la clé et réémettez-en une nouvelle si une clé a été enregistrée dans un référentiel, collée dans un document partagé ou transmise à un prestataire qui n'en a plus besoin.

Les bonnes habitudes

Dans vos requêtes HTTP, faites référence à vos identifiants en utilisant la syntaxe {{ secrets.KEY }} plutôt que de les insérer directement dans un en-tête ou dans le corps de la requête. Les identifiants saisis en clair sont masqués dans les réponses de l’API, mais il est préférable de faire référence à un secret.
Utilisez une clé par consommateur, afin de pouvoir révoquer une seule intégration sans affecter les autres.
Veillez à ce qu'aucune clé d'exécution ne figure sur les ordinateurs portables des développeurs ni dans les configurations des assistants IA, sauf si vous souhaitez expressément que l'assistant puisse envoyer des requêtes en temps réel.