# Authentification

> Authentifiez les requêtes API avec une clé API ou un jeton d’accès OAuth en Bearer, choisissez la portée full ou sending, restreignez les clés à un domaine et gérez les erreurs d’authentification.

Chaque requête adressée à l’API Emailit doit comporter un identifiant dans l’en-tête `Authorization`. Cette page présente les deux types d’identifiants (clés API et jetons d’accès OAuth), ce que permet chaque portée et toutes les erreurs d’authentification que vous pouvez recevoir.

## Clés API

Une clé API appartient à un espace de travail, et chaque requête effectuée avec elle agit sur cet espace de travail. Les clés se présentent ainsi :

```text
secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG
```

Soit `secret_` suivi de 32 lettres et chiffres. Les clés créées avant le format `secret_` n’ont pas de préfixe et continuent de fonctionner.

Créez des clés dans le tableau de bord, sous **Email API → API Keys**, ou avec [Créer une clé API](/fr/docs/api-reference/api-keys/create/). Le secret n’est affiché qu’une seule fois, lorsque vous créez ou [régénérez](/fr/docs/api-reference/api-keys/regenerate/) la clé : enregistrez-le immédiatement. Pour les gérer, consultez [Clés API](/fr/docs/developers/api-keys/).

Les mêmes clés servent de mot de passe SMTP pour le [relais SMTP](/fr/docs/smtp/settings/).

## Envoyer la clé avec chaque requête

Utilisez le schéma `Bearer` dans l’en-tête `Authorization`. L’API n’accepte pas de clé dans la chaîne de requête ni dans le corps de la requête.

**cURL**

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()
```

Les SDK définissent cet en-tête pour vous lorsque vous transmettez la clé au client.

## Portées

Chaque clé possède l’une des deux portées. Vous la choisissez à la création de la clé et ne pouvez plus la modifier ensuite.

| Portée | Peut appeler | Utilisation |
| --- | --- | --- |
| `full` | Tous les endpoints de l’API. C’est la valeur par défaut. | Outils de back-office, scripts et intégrations qui gèrent des domaines, des contacts, des modèles ou des webhooks. |
| `sending` | Uniquement les endpoints d’envoi listés ci-dessous. | Serveurs applicatifs qui ne font qu’envoyer des e-mails. |

Une clé `sending` peut appeler ces endpoints, et aucun autre :

| Endpoint | Description |
| --- | --- |
| `POST /emails` | [Envoyer un e-mail](/fr/docs/api-reference/emails/send/) |
| `POST /emails/{id}` | [Mettre à jour un e-mail programmé](/fr/docs/api-reference/emails/update/) |
| `POST /emails/{id}/cancel` | [Annuler un e-mail](/fr/docs/api-reference/emails/cancel/) |
| `POST /emails/{id}/retry` | [Relancer un e-mail](/fr/docs/api-reference/emails/retry/) |
| `POST /emails/{id}/forward` | [Transférer un e-mail](/fr/docs/api-reference/emails/forward/) |

La lecture des e-mails (liste, récupération, MIME brut, corps, métadonnées, pièces jointes et statut) nécessite une clé `full`. Lorsqu’une clé `sending` appelle un autre endpoint, l’API renvoie `403` avec `Permission denied: full` (ou `Permission denied: read` pour les endpoints de lecture des e-mails).

La page [Tous les endpoints](/fr/docs/api-reference/endpoints/) indique la portée de chaque endpoint.

## Restreindre une clé à un domaine

Une clé `sending` peut aussi être limitée à un seul domaine d’envoi. Transmettez l’ID du domaine dans `sending_domain_id` lorsque vous [créez la clé](/fr/docs/api-reference/api-keys/create/). Une clé restreinte ne peut envoyer que depuis des adresses de ce domaine. Tout autre domaine dans `from` renvoie `403` :

```json
{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}
```

Les restrictions de domaine ne s’appliquent qu’aux clés `sending`. Une clé `full` a toujours accès à tous les domaines de l’espace de travail.

## Jetons d’accès OAuth

Les applications qui agissent pour le compte d’un utilisateur Emailit, comme les clients MCP et les intégrations tierces, ne demandent pas de clé API. Elles utilisent OAuth 2.1 : l’utilisateur se connecte à Emailit, choisit les espaces de travail que l’application peut utiliser (tous ou seulement certains) et approuve la portée `sending` ou `full`, puis l’application reçoit un jeton d’accès. L’utilisateur peut modifier ou révoquer cet accès depuis [Applications connectées](/fr/docs/account/connected-apps/).

Envoyez les jetons d’accès dans le même en-tête que les clés API :

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
```

Un jeton d’accès est valable 15 minutes et agit sur l’espace de travail par défaut de l’autorisation, avec la portée accordée et le rôle de l’utilisateur dans cet espace de travail. Les applications le renouvellent avec le jeton d’actualisation. Pour créer une application OAuth, consultez [Applications OAuth](/fr/docs/developers/oauth-apps/).

## Erreurs d’authentification

L’authentification a lieu avant tout le reste : ces erreurs peuvent donc provenir de n’importe quel endpoint.

| Statut | `message` ou `error` | Cause | Solution |
| --- | --- | --- | --- |
| `401` | `API key required` | L’en-tête `Authorization` est absent ou ne commence pas par `Bearer `. | Envoyez `Authorization: Bearer <key>`. |
| `401` | `Valid API key required` | L’en-tête contient le préfixe `Bearer`, mais aucun jeton. | Vérifiez que la variable qui contient votre clé n’est pas vide. |
| `401` | `Invalid API key` | La clé n’existe pas, a été supprimée ou a été régénérée (l’ancien secret cesse de fonctionner), ou un jeton OAuth a expiré. | Utilisez une clé valide ou actualisez le jeton OAuth. |
| `403` | `Workspace is suspended` | L’espace de travail est suspendu. | Contactez le [support](/contact/). |
| `403` | `Permission denied: full` | Une clé `sending` a appelé un endpoint qui nécessite `full`. | Utilisez une clé `full`. |
| `403` | `Domain not authorized` | Une clé limitée à un domaine a envoyé depuis un autre domaine. | Envoyez depuis le domaine de la clé ou utilisez une autre clé. |
| `403` | `unverified_workspace_recipient` | L’espace de travail n’est pas encore vérifié et un destinataire n’est pas membre de l’espace de travail. | Consultez [Espaces de travail non vérifiés](#unverified-workspaces). |
| `503` | `Authentication service unavailable` | Un problème temporaire de notre côté. | Relancez avec un intervalle exponentiel. |

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**403 Portée**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}
```

**403 Suspendu**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}
```

**403 Non vérifié**

```json
{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}
```

## Espaces de travail non vérifiés

Les nouveaux espaces de travail démarrent non vérifiés. Tant qu’Emailit n’a pas approuvé l’[accès production](/fr/docs/workspaces/production-access/), l’API n’envoie qu’aux adresses e-mail de compte des membres de l’espace de travail. Un envoi, une relance ou un transfert vers toute autre personne renvoie `403` avec le code `unverified_workspace_recipient` et la liste `blocked_recipients`, et aucune campagne ne peut être envoyée. Vos clés API fonctionnent normalement pour tout le reste.

## Garder vos clés secrètes

Une clé API donne accès à votre espace de travail : traitez-la comme un mot de passe.

- Appelez l’API uniquement depuis votre serveur. Ne placez jamais une clé dans du JavaScript exécuté dans le navigateur, dans une application mobile ni dans tout autre code qui s’exécute sur l’appareil de quelqu’un d’autre.
- Ne mettez pas les clés sous contrôle de version. Chargez-les depuis des variables d’environnement ou un gestionnaire de secrets.
- Créez une clé par application et par environnement, et nommez-la d’après l’endroit où elle est utilisée : vous pourrez en révoquer une sans casser les autres.
- Donnez à chaque clé l’accès minimal dont elle a besoin : une clé `sending` limitée à un domaine suffit à la plupart des applications.
- Vérifiez `last_used_at` avec [Lister les clés API](/fr/docs/api-reference/api-keys/list/) et supprimez les clés que vous n’utilisez plus.
- Si une clé fuite, [régénérez-la](/fr/docs/api-reference/api-keys/regenerate/) ou [supprimez-la](/fr/docs/api-reference/api-keys/delete/) sans attendre. L’ancien secret cesse immédiatement de fonctionner.

## Voir aussi

  - [Clés API](/fr/docs/developers/api-keys/): Créez et restreignez les clés, et effectuez leur rotation dans le tableau de bord.
  - [Erreurs](/fr/docs/api-reference/errors/): Tous les formats d’erreur et codes de statut.
  - [Applications OAuth](/fr/docs/developers/oauth-apps/): Permettez aux utilisateurs de connecter votre application à leur espace de travail.
  - [Accès production](/fr/docs/workspaces/production-access/): Faites vérifier votre espace de travail pour envoyer à n’importe qui.

---
Source: https://emailit.com/fr/docs/api-reference/authentication/