--- title: "mTLS" description: "Exigez un certificat client sur les requêtes API via le point de terminaison mTLS, et présentez un certificat client lors des livraisons de webhooks à vos récepteurs." canonical: "https://bird.com/fr-fr/documentation/guides/mtls" availability: "on-request" --- # mTLS Le TLS mutuel (mTLS) ajoute une vérification de certificat dans les deux sens lors de la négociation TLS. Chaque sens a ses propres paramètres. Vous pouvez configurer un seul sens ou les deux. | Sens | Client TLS | Serveur TLS | Paramètres | | ---------------------- | ------------ | ---------------------------- | ------------------------------------------------------------------------------- | | Requêtes API | Vos systèmes | Le point de terminaison mTLS | [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls) | | Livraisons de webhooks | Nous | Vos récepteurs | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls) | Chaque partie conserve ses propres clés privées. Pour les requêtes API, vous nous fournissez le certificat public de votre autorité de certification (CA). Pour les livraisons de webhooks, nous vous fournissons une demande de signature de certificat (CSR), et vous nous renvoyez le certificat public signé. ## Avant de commencer - Contactez votre représentant Bird pour activer le mTLS API, le mTLS des webhooks, ou les deux, pour votre organisation. Chaque sens s'active séparément. - Obtenez un rôle disposant d'un accès en écriture au scope `access_restrictions` dans l'espace de travail. Pour envoyer des événements de test de webhook, obtenez aussi un accès en écriture au scope `webhooks`. - Pour les requêtes API, procurez-vous le certificat PEM de la CA qui émet vos certificats client. Préférez la CA émettrice à la CA racine : la vérification de la chaîne accepte tout certificat qui remonte jusqu'à une CA enregistrée, donc une CA racine laisse aussi passer les certificats de ses autres CA émettrices. Chaque certificat doit tout de même réussir les autres vérifications, comme l'usage étendu de clé `clientAuth`. - Pour les livraisons de webhooks, préparez une CA capable de signer une CSR avec l'usage étendu de clé `clientAuth`. ## Exiger des certificats client pour les requêtes API Chaque région dispose d'un endpoint mTLS. Il propose les mêmes opérations que l'endpoint standard et demande un certificat à chaque client. | Région | Endpoint standard | Endpoint mTLS | | ------ | ------------------------------- | ------------------------------------ | | `eu1` | `https://eu1.platform.bird.com` | `https://mtls.eu1.platform.bird.com` | | `us1` | `https://us1.platform.bird.com` | `https://mtls.us1.platform.bird.com` | Le certificat client ne remplace pas vos identifiants. Chaque requête envoie toujours une clé API, un jeton OAuth ou un jeton de compte de service dans l'en-tête `Authorization`. Le mode est un paramètre de l'espace de travail. Il détermine quel endpoint accepte les requêtes adressées à l'espace de travail avec une clé API, un jeton OAuth ou un jeton de compte de service. | Mode | Endpoint standard | Endpoint mTLS | | ------------ | -------------------- | --------------------------------------------------------------- | | `disabled` | Accepte les requêtes | Rejette les requêtes | | `evaluating` | Accepte les requêtes | Accepte les requêtes accompagnées d'un certificat client valide | | `enforced` | Rejette les requêtes | Accepte les requêtes accompagnées d'un certificat client valide | Le mode s'applique au trafic suivant. Tout le reste continue de fonctionner, quel que soit le mode. | Trafic | Mode `enforced` | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Requêtes API accompagnées d'une clé API, d'un jeton OAuth ou d'un jeton de compte de service | L'endpoint standard les rejette avec [`E02090`](/docs/api/errors/E02090). | | Envoi via [SMTP](/docs/guides/email/smtp) | Refusé. SMTP ne peut pas présenter de certificat client. | | Le serveur MCP hébergé | Ne peut pas accéder à l'espace de travail. Il ne peut pas présenter votre certificat client. | | Sessions du dashboard | Non concernées. | | Automations | Non concernées. | | Requêtes accompagnées d'un identifiant d'organisation sur des opérations d'organisation | Non vérifiées. Le mode appartient à un espace de travail, et ces requêtes n'en désignent aucun. | | [Trunks SIP](/docs/guides/voice/sip-trunks) | Non concernés. Un trunk continue d'authentifier les appels avec une clé API autorisée, sans certificat. | Un changement de mode s'applique immédiatement aux nouvelles requêtes. Une session SMTP ouverte reçoit le nouveau mode à son message suivant. Un certificat client valide remonte jusqu’à une CA de l’espace de travail, se trouve dans sa période de validité et possède l’usage étendu de clé `clientAuth`. Si vous définissez un nom alternatif du sujet (SAN) obligatoire, le certificat doit aussi le contenir. Nous comparons les noms DNS et les URI. Nous n’utilisons pas le nom commun. ### Ajouter votre autorité de certification 1. Ouvrez [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls). 2. Dans **Certificate authorities**, sélectionnez **Add certificate authority**. 3. Collez le certificat PEM de votre CA ou choisissez un fichier. 4. Sélectionnez **Add certificate authority**. Le certificat doit posséder la contrainte de base `CA:true` et l’usage de clé `keyCertSign`, et il ne doit pas être expiré. Un espace de travail peut avoir deux CA. Si votre CA émet aussi des certificats pour d’autres parties, définissez **Required subject alternative name** sur l’identité que portent vos certificats clients. ### Tester en mode évaluation 1. Dans **Mode**, sélectionnez **Evaluating**, puis **Save**. 2. Configurez votre client pour qu’il présente son certificat. Si une CA intermédiaire signe le certificat client, envoyez aussi le certificat intermédiaire. 3. Remplacez l’URL de base de votre client par celle du point de terminaison mTLS. 4. Envoyez une requête de test : ```bash curl https://mtls.eu1.platform.bird.com/v1/workspace \ --cert client.pem \ --key client.key \ -H "Authorization: Bearer $BIRD_API_KEY" ``` Une réponse autre que `401` indique que la vérification du certificat a réussi. Une réponse `401` contient un code d'erreur. La section [Dépannage](#dépannage) indique la cause de chaque code. Pour identifier les appelants que le mode `enforced` refuserait, filtrez les journaux de requêtes de l'espace de travail sur **mTLS** `missing`. Les journaux de requêtes enregistrent les écritures, comme les requêtes `POST`, `PATCH` et `DELETE`, ainsi que les envois SMTP. Ils n'enregistrent pas les lectures : vérifiez donc séparément les clients qui ne font que lire, car le mode `enforced` les refuse aussi. ### Imposer mTLS 1. Faites passer chaque intégration sur le point de terminaison mTLS. 2. Dans **Mode**, sélectionnez **Enforced**, puis sélectionnez **Save**. L'endpoint standard rejette désormais les requêtes accompagnées d'une clé API, d'un jeton OAuth ou d'un jeton de compte de service de l'espace de travail avec [`E02090`](/docs/api/errors/E02090). Le serveur MCP hébergé ne peut pas accéder à l'espace de travail. Utilisez plutôt le serveur MCP local de la [CLI Bird](#utiliser-la-cli-bird). L'endpoint SMTP refuse l'AUTH pour l'espace de travail avec `535 5.7.8`. Une session SMTP ouverte reçoit `530 5.7.0` à son message suivant. Envoyez plutôt les e-mails via l'API sur l'endpoint mTLS. Une modification des CA ou du SAN requis peut mettre jusqu'à 15 minutes à s'appliquer à chaque requête. ### Utiliser la CLI Bird La [CLI Bird](/docs/cli) et son serveur MCP local (`bird mcp`) présentent votre certificat client avec ces paramètres : | Paramètre | Option | Variable d'environnement | | --------------------------------------------------------- | --------------- | ------------------------ | | Chaîne de certificats, PEM, certificat feuille en premier | `--client-cert` | `BIRD_CLIENT_CERT` | | Clé privée, PEM, non chiffrée | `--client-key` | `BIRD_CLIENT_KEY` | | Envoyer les requêtes au point de terminaison mTLS | `--mtls` | `BIRD_MTLS=1` | ```bash export BIRD_API_KEY=bk_eu1_... export BIRD_CLIENT_CERT=client.pem export BIRD_CLIENT_KEY=client.key bird workspace get --mtls ``` Pour conserver ces paramètres avec une connexion OAuth, passez les trois options à `bird auth login`. Le profil enregistre les chemins des fichiers, et les commandes suivantes utilisent l'endpoint mTLS sans options. `bird auth status` affiche l'empreinte SHA-256 et la date d'expiration du certificat. ### Utiliser un SDK Indiquez au SDK les chemins de votre chaîne de certificats (PEM, certificat feuille en premier) et de sa clé privée (PEM, non chiffrée). Le SDK présente le certificat à chaque requête et envoie les requêtes au point de terminaison mTLS de la région de votre clé API. Si vous définissez une URL de base, le SDK utilise cette URL. Le SDK refuse un certificat fourni avec un client HTTP que vous fournissez vous-même. Pour utiliser votre propre client HTTP, configurez le certificat sur ce client et définissez l’URL de base sur le point de terminaison mTLS. **TypeScript** ```typescript // Node.js only. Install the optional undici dependency if your package manager skipped it. import { BirdClient } from "@messagebird/sdk"; const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY!, clientCertificate: { cert: "client.pem", key: "client.key" }, }); const workspace = await bird.workspace.get(); console.log(workspace.id); ``` Examples: [TypeScript](/fr-fr/documentation/guides/mtls.ts.md) · [Python](/fr-fr/documentation/guides/mtls.py.md) · [Go](/fr-fr/documentation/guides/mtls.go.md) · [PHP](/fr-fr/documentation/guides/mtls.php.md) ## Présenter un certificat client lors des livraisons de webhooks Nous générons une paire de clés RSA 2048 et une CSR avec le sujet `CN=, O=Bird`. La clé privée reste chez nous. Votre CA signe la CSR, et nous présentons le certificat signé lorsque votre récepteur en demande un. Nous présentons le certificat pour les abonnements webhook et les rappels directs, y compris lors des nouvelles tentatives. Les livraisons suivantes ne le présentent pas : - Événements `realtime.*` - Points de terminaison des connecteurs - Abonnements MCP Events | Mode | Comportement de livraison | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `disabled` | Nous ne présentons pas de certificat. | | `evaluating` | Nous présentons le certificat lorsque le récepteur en demande un. Si le récepteur le refuse, nous livrons à nouveau sans certificat. | | `enforced` | Nous présentons le certificat. Si le récepteur ne le demande pas ou le refuse, la tentative de livraison échoue. | ### Signer et téléverser le certificat 1. Ouvrez [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls). 2. Dans **Certificate**, sélectionnez **Create signing request**. 3. Dans **Signing request**, sélectionnez **Download**. 4. Faites signer la CSR par votre CA avec l'utilisation étendue de clé `clientAuth`. 5. Sélectionnez **Upload certificate**. 6. Collez d'abord le certificat signé, puis chaque certificat intermédiaire dans l'ordre. Vous pouvez aussi choisir un fichier. 7. Sélectionnez **Upload certificate**. Nous vérifions que le certificat correspond à la clé de la demande de signature, qu'il possède l'utilisation étendue de clé `clientAuth` et qu'il est dans sa période de validité. La section **Certificate** affiche ensuite son sujet, son émetteur, son numéro de série, son empreinte SHA-256 et sa période de validité. ### Configurer vos récepteurs 1. Demandez un certificat client lors de la négociation TLS. 2. Faites confiance à la CA qui a signé notre certificat. 3. Présentez un certificat serveur émis par une CA publiquement reconnue et correspondant au nom d'hôte du récepteur. Pour accepter notre certificat et aucun autre certificat émis par votre CA, vérifiez le sujet `CN=` ou l'empreinte SHA-256. ### Appliquer le mTLS des webhooks 1. Dans **Mode**, sélectionnez **Evaluating**, puis **Save**. 2. Envoyez un événement de test à chaque webhook avec [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook). Vérifiez que `client_certificate` vaut `presented`. `not_requested` signifie que le récepteur n'a pas demandé le certificat, et `rejected` signifie qu'il ne l'a pas accepté. 3. Pour les [URL de rappel SMS](/docs/guides/sms/callbacks), qui n'ont pas d'ID de webhook, envoyez un SMS avec `options.callback_url` défini sur le récepteur. Consultez les journaux du récepteur et vérifiez que le rappel présente notre certificat. En mode `evaluating`, un certificat refusé apparaît aussi dans [`GET /v1/webhook-callbacks/attempts`](/docs/api/reference/list-webhook-callback-attempts) comme une tentative échouée avec un `failure_reason`. 4. Dans **Mode**, sélectionnez **Enforced**, puis **Save**. En mode `enforced`, un certificat refusé apparaît comme une tentative échouée dans les [tentatives de livraison](/docs/guides/webhooks#replaying-failed-deliveries) du webhook. ## Vérifier la révocation Définissez **Certificate revocation list check** sur **Full chain** pour vérifier la révocation à l'aide des listes de révocation de certificats (CRL). - Pour les requêtes API, nous vérifions le certificat client et chaque certificat intermédiaire situé sous votre autorité de certification. - Pour les livraisons de webhooks, nous vérifions le certificat serveur de votre récepteur et chaque certificat intermédiaire situé sous sa racine. Nous vérifions chaque point de distribution de CRL du certificat. Les URI `http` et `https` d'un même point de distribution sont des miroirs de la même CRL, et nous utilisons le premier miroir qui répond. Un point de distribution sans URI `http` ou `https` fait échouer la vérification. Un certificat sans point de distribution de CRL n'est pas vérifié. Nous vérifions la signature de chaque CRL. Si nous ne pouvons pas obtenir de CRL valide, nous refusons la requête ou faisons échouer la tentative de livraison. | Limite | Valeur | | --------------------------------- | -------------------------------------------------------------- | | Durée de téléchargement d'une CRL | 5 secondes par téléchargement, 10 secondes par requête | | Taille d'une CRL | 10 Mio | | CRL par espace de travail | 10 pour les requêtes API et 10 pour les livraisons de webhooks | ## Renouveler les certificats Nous envoyons un e-mail aux contacts de l'espace de travail 30 jours et 7 jours avant l'expiration d'une CA ou du certificat client des webhooks. Pour renouveler la CA des requêtes API : 1. Ajoutez la nouvelle CA. L'espace de travail fait alors confiance aux deux CA. 2. Faites passer chaque intégration à un certificat client émis par la nouvelle CA. 3. Supprimez l'ancienne CA. Vous ne pouvez pas supprimer la dernière CA tant que le mode est `evaluating` ou `enforced`. Les certificats client émis par votre CA ne demandent aucune action en mode Bird. Pour renouveler le certificat client des webhooks : 1. Sélectionnez **Create new signing request**. 2. Faites signer la nouvelle CSR, puis importez le certificat. Le certificat actuel reste utilisé jusqu'à ce que vous importiez le nouveau. Les envois de test utilisent immédiatement le nouveau certificat, mais les livraisons peuvent continuer à présenter l'ancien pendant quelques minutes au plus. D'ici là, vos récepteurs doivent accepter les deux certificats, par CA ou par empreinte. ## Automatiser avec l'API Chaque action du dashboard correspond à une opération API. Envoyez ces appels à un endpoint accepté par votre mode : l'endpoint standard en mode `disabled` ou `evaluating`, et l'endpoint mTLS avec un certificat client en mode `enforced`. La clé API doit disposer d'un accès en écriture au scope `access_restrictions`. Les clés maîtres d'organisation ne peuvent pas utiliser ces opérations. | Opération | Action | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [`PATCH /v1/workspace/mtls-settings`](/docs/api/reference/update-workspace-mtls-settings) | Modifier `state`, `expected_san` ou `crl_check` | | [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority) | Ajouter une CA | | [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority) | Supprimer une CA | | [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate) | Modifier `state` ou `crl_check` | | [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | Créer une CSR | | [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate) | Importer le certificat signé | ```bash curl -X PATCH https://eu1.platform.bird.com/v1/workspace/mtls-settings \ -H "Authorization: Bearer $BIRD_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"state": "enforced", "crl_check": "full_chain"}' ``` ## Dépannage Les requêtes API qui échouent à une vérification renvoient `401` avec l'un des codes suivants : | Code | Cause | | ----------------------------------- | --------------------------------------------------------------------------------- | | [`E02086`](/docs/api/errors/E02086) | La requête n'a présenté aucun certificat client. | | [`E02087`](/docs/api/errors/E02087) | Le certificat client n'est pas valide pour l'espace de travail. | | [`E02088`](/docs/api/errors/E02088) | Un certificat de la chaîne est révoqué. | | [`E02089`](/docs/api/errors/E02089) | Le mode est `disabled`, donc le point de terminaison mTLS rejette la requête. | | [`E02090`](/docs/api/errors/E02090) | Le mode est `enforced`, donc le point de terminaison standard rejette la requête. | | [`E02091`](/docs/api/errors/E02091) | Nous n’avons pas pu télécharger une CRL en moins de 5 secondes. | | [`E02092`](/docs/api/errors/E02092) | Une CRL dépasse 10 Mio. | | [`E02093`](/docs/api/errors/E02093) | L’espace de travail utilise déjà 10 CRL. | | [`E02094`](/docs/api/errors/E02094) | Une CRL a une signature non valide ou a dépassé sa date de prochaine mise à jour. | Une modification de paramètre peut renvoyer l’un de ces codes : - [`E10027`](/docs/api/errors/E10027) : le mTLS API n’est pas activé pour l’espace de travail. Contactez votre représentant Bird pour l’activer. - [`E10028`](/docs/api/errors/E10028) : le mTLS des webhooks n’est pas activé pour l’espace de travail. Contactez votre représentant Bird pour l’activer. ## Étapes suivantes - [Authentification](/docs/guides/authentication) : clés API, portées et comptes de service - [Webhooks et événements](/docs/guides/webhooks) : créer des endpoints et vérifier les signatures - [Erreurs](/docs/guides/errors) : la réponse d'erreur et comment la traiter ## Related resources - [Webhooks done right: reliable delivery events](/learn/basics/webhooks-done-right-reliable-delivery-events) (video) - [How do I verify a webhook signature?](/explained/platform/how-do-i-verify-a-webhook-signature) (answer) - [SMTP relay](/email-api/features/smtp) (product) - [Operate messaging reliably](/learn/paths/reliability) (course)