RÉFÉRENCE API

Clés API

Une clé API authentifie vos appels serveur à serveur (POST /v1/emails). Elle est distincte de la session de votre compte, utilisée par le tableau de bord pour gérer domaines, clés et facturation.

Créer une clé

Depuis le tableau de bord, Clés API → Nouvelle clé, donnez-lui un nom qui vous aidera à la reconnaître plus tard (ex. « Serveur de production », « Script de test »). La clé complète a la forme suivante :

zd_live_9fQ2mR7xL0pK4wT8nB1vD6sH3jY5cZ2aE9uI7oP

Utilisez-la dans l’en-tête Authorization de vos appels à l’API :

Authorization: Bearer zd_live_9fQ2mR7xL0pK4wT8nB1vD6sH3jY5cZ2aE9uI7oP

Affichage unique

La clé complète n’apparaît qu’au moment de sa création. Une fois l’écran quitté, seul son préfixe (les 12 premiers caractères, ex. zd_live_9fQ2) reste visible dans la liste — suffisant pour identifier une clé, jamais pour l’utiliser. Zendou ne stocke que l’empreinte de la clé, jamais la clé en clair : si vous la perdez, il n’y a aucun moyen de la récupérer, seulement d’en créer une nouvelle.

Copiez-la avant de fermer l'écran

Une fois quitté, l’écran de création ne réaffichera plus jamais la clé complète. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Stockage sûr

Une clé API donne un accès direct à l’envoi d’emails — traitez-la comme un mot de passe.

✓Stockez-la dans des variables d’environnement (.env, secret manager, variables d’environnement de votre plateforme de déploiement) — jamais en dur dans le code source.
✓Ne la committez jamais dans le dépôt Git, y compris dans l’historique — un secret poussé une seule fois doit être considéré comme compromis et révoqué.
✓N’appelez jamais POST /v1/emails depuis du code exécuté dans le navigateur : la clé serait visible dans le code source livré au client. Passez toujours par votre serveur.
✓Ajoutez .env à votre .gitignore avant d’y écrire la moindre clé.

Une clé par environnement

Créez une clé distincte pour chaque environnement (production, tests, script local) plutôt que de réutiliser la même partout. Ainsi, une fuite en environnement de test n’expose pas la production, et révoquer une clé compromise n’interrompt pas les autres.

Révocation

Depuis la liste des clés, « Révoquer » désactive la clé immédiatement et définitivement — l’action est irréversible. Toute requête authentifiée avec une clé révoquée répond 401, avec le message « Clé API invalide ou révoquée ». Révoquer une clé n’affecte pas les emails déjà en file ou déjà envoyés avec.

Endpoint	Description
POST /v1/api-keys	Crée une clé. Corps : `{ name }`. La clé complète n’est renvoyée que dans cette réponse.
GET /v1/api-keys	Liste vos clés (nom, préfixe, dates, statut) — jamais la clé complète.
DELETE /v1/api-keys/:id	Révoque la clé.

Ces trois endpoints sont authentifiés par la session du tableau de bord (cookie), pas par une clé API — c’est elle qui les gère, pas l’inverse.

Voir aussi Erreurs pour le détail des réponses 401 et 403.