Clés API

Les clés API authentifient vos requêtes vers l’API REST, vos connexions SMTP et les sessions par clé API sur le serveur MCP. Cette page présente les deux portées de clé, explique comment créer et gérer les clés, et comment les stocker et effectuer leur rotation en toute sécurité.

Fonctionnement des clés API

• Chaque clé appartient à un espace de travail. Tout ce que vous faites avec elle se passe dans cet espace de travail.
• Les nouvelles clés commencent par secret_ suivi de 32 lettres et chiffres, par exemple secret_••••••••. Les clés créées avant l’introduction de ce préfixe continuent de fonctionner.
• Emailit affiche la clé complète une seule fois, lorsque vous la créez ou la régénérez. Copiez-la à ce moment-là : vous ne pourrez plus la consulter.
• Vous transmettez la clé comme jeton bearer : Authorization: Bearer secret_…. Pour le SMTP, la clé sert de mot de passe.

Portées

Chaque clé a l’une des deux portées. Vous choisissez la portée à la création de la clé.

Une clé Sending Only qui appelle un autre endpoint reçoit 403 avec un message comme Permission denied: read. Utilisez des clés Full Access pour les tâches de back-office qui gèrent des ressources, et des clés Sending Only pour tout ce qui ne fait qu’envoyer.

Limiter une clé à un domaine

Lorsque vous créez une clé Sending Only, vous pouvez choisir un domaine d’envoi vérifié. La clé ne peut alors envoyer que depuis des adresses de ce domaine :

• Via l’API, un envoi depuis un autre domaine renvoie 403 avec "error": "Domain not authorized".
• Via SMTP, le message est rejeté après DATA avec 530 API key is restricted to sending domain: ….

Les clés limitées conviennent bien aux identifiants propres à une application ou à un client, et aux clés que vous devez confier à un logiciel tiers, comme un plugin de CMS.

Avant de commencer

• Vous devez avoir le rôle Admin dans l’espace de travail pour créer, modifier, régénérer ou supprimer des clés. Les membres voient la liste des clés, mais ne peuvent pas la modifier. Consultez Membres et rôles.
• Pour envoyer avec une clé, vous avez besoin d’au moins un domaine d’envoi vérifié.

Créer une clé API

curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'

{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}

Utiliser la clé

Transmettez la clé dans l’en-tête Authorization de chaque requête API :

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'

Pour envoyer via SMTP, utilisez la clé comme mot de passe :

Pour toutes les options, consultez Paramètres SMTP.

Gérer les clés

Ouvrez une clé depuis Email API›API Keys pour voir sa portée, son domaine, sa date Created, son heure Last used et les paramètres SMTP à utiliser avec elle.

Last used est mis à jour chaque fois que la clé authentifie une requête API ou une connexion SMTP. Une clé qui n’a jamais servi affiche Never. Dans l’API, les endpoints qui prennent un ID de clé acceptent aussi le nom de la clé.

Stocker les clés en sécurité

• Gardez les clés côté serveur. Ne placez jamais une clé dans du JavaScript exécuté dans le navigateur, une application mobile, un dépôt public ou un ticket de support. Toute personne qui possède la clé peut envoyer des e-mails en votre nom et dépenser vos crédits.
• Utilisez des variables d’environnement ou un gestionnaire de secrets. Chargez la clé à l’exécution, par exemple depuis EMAILIT_API_KEY. Ajoutez les fichiers .env à .gitignore.
• Donnez à chaque application et à chaque environnement sa propre clé. Des clés distinctes pour la production, la préproduction et chaque outil tiers permettent de voir facilement qui a envoyé quoi et d’en révoquer une sans toucher aux autres.
• Utilisez la portée la plus restreinte. Si une application ne fait qu’envoyer des e-mails, donnez-lui une clé Sending Only, limitée à son domaine si possible.
• Surveillez l’utilisation. Email API›Logs liste les requêtes API et SMTP par clé, et vous pouvez filtrer Email API›Emails par clé API. Consultez Logs de requêtes.
• Réagissez vite en cas de fuite. Si une clé est exposée, régénérez-la ou supprimez-la immédiatement, puis vérifiez dans les logs qu’aucun envoi inattendu n’a eu lieu.

Effectuer la rotation d’une clé sans interruption de service

La régénération d’une clé coupe immédiatement l’ancien secret : ne l’utilisez que si une clé est compromise. Pour une rotation planifiée, faites fonctionner l’ancienne et la nouvelle clé en parallèle :

1. Créez une nouvelle clé. Ajoutez une clé avec la même portée et la même limitation de domaine que celle que vous remplacez. Donnez-lui un nom qui indique la date, comme production-web-2026-10.

2. Déployez la nouvelle clé. Mettez à jour le secret dans votre gestionnaire de secrets ou votre environnement et déployez-le sur chaque serveur, worker et tâche planifiée qui utilise l’ancienne clé.

3. Confirmez la bascule. Ouvrez la nouvelle clé et vérifiez que Last used est récent. Dans Email API›Logs, filtrez sur l’ancienne clé et vérifiez que les requêtes ont cessé.

4. Supprimez l’ancienne clé. Quand l’heure Last used de l’ancienne clé ne change plus, supprimez-la.

Dépannage

Voir aussi