# Clés API

> Créez des clés API Full Access et Sending Only, limitez-les à un domaine, utilisez-les pour le SMTP et effectuez leur rotation sans interruption de service.

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é.

| | Full Access (`full`) | Sending Only (`sending`) |
| --- | --- | --- |
| Envoyer un e-mail (`POST /emails`) | Oui | Oui |
| Reprogrammer, annuler, relancer et transférer un e-mail | Oui | Oui |
| Relais SMTP | Oui | Oui |
| Lire les e-mails (liste, récupération, message brut, corps, métadonnées, pièces jointes) | Oui | Non |
| Domaines, modèles, contacts, listes de contacts, adresses bloquées, webhooks, événements, campagnes, automatisations, vérification et clés API | Oui | Non |
| Outils MCP | Tous les outils | `send-email`, `update-email`, `cancel-email`, `retry-email`, `forward-email` et `get-current-workspace` |
| Peut être limitée à un domaine d’envoi | Non | Oui |

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](/fr/docs/workspaces/members-and-roles/).
- Pour envoyer avec une clé, vous avez besoin d’au moins un [domaine d’envoi vérifié](/fr/docs/domains/add-a-domain/).

## Créer une clé API

**Tableau de bord**

  1. **Ouvrez les clés API.** Accédez à **Email API → API Keys** et sélectionnez **Add API key**.

  2. **Nommez la clé.** Saisissez un **Name** qui indique où la clé est utilisée, par exemple `production-web` ou `wordpress-blog`. Les noms doivent être uniques dans l’espace de travail.

  3. **Choisissez une portée.** Sous **Scope**, choisissez **Full Access** ou **Sending Only**.

  4. **Limitez éventuellement le domaine.** Pour une clé Sending Only, choisissez un domaine d’envoi sous **Domain**, ou laissez le champ vide pour autoriser tous les domaines vérifiés.

  5. **Créez et copiez la clé.** Sélectionnez **Create**. Copiez la clé depuis la boîte de dialogue et enregistrez-la dans votre gestionnaire de secrets avant de la fermer. Emailit n’affiche la clé qu’une seule fois.

**API**

  Appelez [Créer une clé API](/fr/docs/api-reference/api-keys/create/) avec une clé Full Access. `scope` vaut `full` par défaut ; `sending_domain_id` ne s’applique qu’aux clés Sending Only.

```bash
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"
  }'
```

  La réponse `201` est la seule qui contient `key` :

```json
{
  "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_••••••••••••••••••••••••••••••••"
}
```

  Un nom déjà utilisé renvoie `409`.

## Utiliser la clé

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

```bash
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 :

| Paramètre | Valeur |
| --- | --- |
| Hôte | `smtp.emailit.com` |
| Port | `587` (STARTTLS, recommandé), `465` (TLS), `2525` ou `2587` (STARTTLS) |
| Nom d’utilisateur | `emailit` |
| Mot de passe | Votre clé API |

Pour toutes les options, consultez [Paramètres SMTP](/fr/docs/smtp/settings/).

## 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.

| Action | Ce qui se passe | API |
| --- | --- | --- |
| **Edit** | Renomme la clé. Seul le nom est enregistré ; pour modifier la portée ou la limitation de domaine, créez une nouvelle clé et effectuez la rotation vers celle-ci. | [Mettre à jour une clé API](/fr/docs/api-reference/api-keys/update/) |
| **Regenerate** | Émet un nouveau secret pour la même clé et l’affiche une seule fois. L’ancien secret cesse immédiatement de fonctionner. La clé conserve son ID, son nom, sa portée et son domaine, et **Last used** est réinitialisé. | [Régénérer une clé API](/fr/docs/api-reference/api-keys/regenerate/) |
| **Delete** | La clé cesse immédiatement de fonctionner et disparaît de la liste. Cette action est irréversible. | [Supprimer une clé API](/fr/docs/api-reference/api-keys/delete/) |

**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](/fr/docs/logs/request-logs/).
- **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

| Symptôme | Cause | Solution |
| --- | --- | --- |
| `401` `Invalid API key` | La clé a été supprimée, régénérée ou mal saisie. | Copiez la clé actuelle dans votre configuration, avec le préfixe `secret_`. |
| `403` `Permission denied: read` ou `Permission denied: full` | Une clé Sending Only a appelé un endpoint hors de sa portée. | Utilisez une clé Full Access pour cet appel. |
| `403` `Domain not authorized` | La clé est limitée à un autre domaine que celui de l’adresse `from`. | Envoyez depuis le domaine de la clé ou utilisez une autre clé. |
| SMTP `535 Authentication failed` | Le mot de passe n’est pas une clé API valide. | Utilisez la clé API comme mot de passe et `emailit` comme nom d’utilisateur. |

## Voir aussi

  - [Authentification](/fr/docs/api-reference/authentication/): Comment les requêtes sont authentifiées.
  - [API des clés API](/fr/docs/api-reference/api-keys/): Créer, lister, mettre à jour, régénérer et supprimer des clés.
  - [Paramètres SMTP](/fr/docs/smtp/settings/): Hôte, ports, TLS et identifiants.
  - [Sécurité](/fr/docs/security/): Comment Emailit protège votre compte et vos données.

---
Source: https://emailit.com/fr/docs/developers/api-keys/