mTLS
Available on requestContact your Bird representative to enable it for your organization.
El TLS mutuo (mTLS) añade una comprobación de certificados en ambas direcciones al handshake de TLS. Cada dirección tiene su propia configuración. Puedes configurar una dirección o ambas.
| Dirección | Cliente TLS | Servidor TLS | Configuración |
|---|---|---|---|
| Solicitudes a API | Tus sistemas | El endpoint mTLS | Workspace settings > mTLS |
| Entregas de webhooks | Nosotros | Tus receptores | Webhooks > mTLS |
Cada parte conserva sus propias claves privadas. Para las solicitudes de API, nos das el certificado público de tu autoridad de certificación (CA). Para las entregas de webhooks, te damos una solicitud de firma de certificado (CSR) y tú nos devuelves el certificado público firmado.
Antes de empezar
- Ponte en contacto con tu representante de Bird para habilitar mTLS de API, mTLS de webhooks o ambos en tu organización. Cada dirección se habilita por separado.
- Consigue un rol con acceso de escritura al ámbito
access_restrictionsen el espacio de trabajo. Para enviar eventos de prueba de webhooks, consigue también acceso de escritura al ámbitowebhooks. - Para las solicitudes de API, consigue el certificado PEM de la CA que emite tus certificados de cliente. Usa preferiblemente la CA emisora en lugar de la CA raíz: la comprobación de la cadena acepta todos los certificados que se encadenan a una CA registrada, por lo que una CA raíz también da por válidos los certificados de sus otras CA emisoras. Cada certificado debe superar igualmente las demás comprobaciones, como el uso extendido de clave
clientAuth. - Para las entregas de webhooks, prepara una CA que pueda firmar una CSR con el uso extendido de clave
clientAuth.
Exigir certificados de cliente en las solicitudes de API
Cada región tiene un endpoint mTLS. Ofrece las mismas operaciones que el endpoint estándar y pide un certificado a cada cliente.
| Región | Endpoint estándar | 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 |
El certificado de cliente no sustituye a tu credencial. Cada solicitud sigue enviando una clave de API, un token de OAuth o un token de cuenta de servicio en el encabezado Authorization.
El modo es una configuración del espacio de trabajo. Determina qué endpoint acepta las solicitudes para el espacio de trabajo con una clave de API, un token de OAuth o un token de cuenta de servicio.
| Modo | Endpoint estándar | Endpoint mTLS |
|---|---|---|
disabled | Acepta solicitudes | Rechaza solicitudes |
evaluating | Acepta solicitudes | Acepta solicitudes con un certificado de cliente válido |
enforced | Rechaza solicitudes | Acepta solicitudes con un certificado de cliente válido |
El modo se aplica a este tráfico. Todo lo demás sigue funcionando en todos los modos.
| Tráfico | Modo enforced |
|---|---|
| Solicitudes a API con una clave de API, un token de OAuth o un token de cuenta de servicio | El endpoint estándar las rechaza con E02090. |
| Envío de SMTP | Rechazado. SMTP no puede presentar un certificado de cliente. |
| El servidor MCP alojado | No puede acceder al espacio de trabajo. No puede presentar tu certificado de cliente. |
| Sesiones del panel | No se ven afectadas. |
| Automations | No se ven afectadas. |
| Solicitudes con una credencial de organización en operaciones de organización | No se comprueban. El modo pertenece a un espacio de trabajo, y estas solicitudes no indican ninguno. |
| Troncales de SIP | No se ven afectadas. Una troncal sigue autenticando las llamadas con una clave de API permitida, sin certificado. |
Un cambio de modo se aplica de inmediato a las solicitudes nuevas. Una sesión SMTP abierta recibe el nuevo modo en su siguiente mensaje.
Un certificado de cliente válido se encadena a una CA del espacio de trabajo, está dentro de su periodo de validez y tiene el uso extendido de clave clientAuth. Si configuras un nombre alternativo del sujeto (SAN) obligatorio, el certificado también debe contenerlo. Comparamos nombres DNS y URI. No usamos el nombre común.
Añade tu autoridad de certificación
- Abre Workspace settings > mTLS.
- En Certificate authorities, selecciona Add certificate authority.
- Pega el certificado PEM de tu CA o elige un archivo.
- Selecciona Add certificate authority.
El certificado debe tener la restricción básica CA:true y el uso de clave keyCertSign, y no puede estar caducado. Un espacio de trabajo puede tener dos CA.
Si tu CA también emite certificados para terceros, establece Required subject alternative name con la identidad que llevan tus certificados de cliente.
Prueba en modo de evaluación
- En Mode, selecciona Evaluating y, después, Save.
- Configura tu cliente para que presente su certificado. Si una CA intermedia firma el certificado de cliente, envía también el certificado intermedio.
- Cambia la URL base de tu cliente al endpoint mTLS.
- Envía una solicitud de prueba:
curl https://mtls.eu1.platform.bird.com/v1/workspace \
--cert client.pem \
--key client.key \
-H "Authorization: Bearer $BIRD_API_KEY"Si la respuesta no es 401, la comprobación del certificado se ha superado. Una respuesta 401 contiene un código de error. En Solución de problemas se indica la causa de cada código.
Para encontrar los clientes que el modo enforced rechazaría, filtra los registros de solicitudes del espacio de trabajo por mTLS missing. Los registros de solicitudes guardan las escrituras, como las solicitudes POST, PATCH y DELETE, y los envíos de SMTP. No guardan las lecturas, así que comprueba por separado los clientes que solo leen: el modo enforced también los rechaza.
Exigir mTLS
- Migra cada integración al endpoint mTLS.
- En Mode, selecciona Enforced y, después, Save.
A partir de ese momento, el endpoint estándar rechaza las solicitudes del espacio de trabajo con una clave de API, un token de OAuth o un token de cuenta de servicio con E02090.
El servidor MCP alojado no puede acceder al espacio de trabajo. En su lugar, usa el servidor MCP local de la CLI de Bird.
El endpoint SMTP rechaza AUTH para el espacio de trabajo con 535 5.7.8. Una sesión SMTP abierta recibe 530 5.7.0 en su siguiente mensaje. En su lugar, envía el correo electrónico a través de API en el endpoint mTLS.
Un cambio en las CA o en el SAN obligatorio puede tardar hasta 15 minutos en aplicarse a cada solicitud.
Usa la CLI de Bird
La CLI de Bird y su servidor MCP local (bird mcp) presentan tu certificado de cliente con esta configuración:
| Ajuste | Flag | Variable de entorno |
|---|---|---|
| Cadena de certificados, PEM, primero el certificado final | --client-cert | BIRD_CLIENT_CERT |
| Clave privada, PEM, sin cifrar | --client-key | BIRD_CLIENT_KEY |
| Enviar solicitudes al endpoint mTLS | --mtls | BIRD_MTLS=1 |
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtlsPara conservar la configuración con un inicio de sesión de OAuth, pasa las tres opciones a bird auth login. El perfil guarda las rutas de los archivos, y los comandos posteriores usan el endpoint mTLS sin opciones. bird auth status muestra la huella digital SHA-256 y la fecha de caducidad del certificado.
Usa un SDK
Indica al SDK las rutas de tu cadena de certificados (PEM, primero el certificado final) y de su clave privada (PEM, sin cifrar). El SDK presenta el certificado en cada solicitud y envía las solicitudes al endpoint mTLS de la región de tu clave de API. Si defines una URL base, el SDK usa esa URL.
El SDK rechaza un certificado junto con un cliente HTTP que proporciones tú. Para usar tu propio cliente HTTP, configura el certificado en ese cliente y define como URL base el endpoint mTLS.
// 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);import os
from bird import Bird
# client_cert and client_key also fall back to BIRD_CLIENT_CERT and BIRD_CLIENT_KEY.
client = Bird(
api_key=os.environ["BIRD_API_KEY"],
client_cert="client.pem",
client_key="client.key",
)
workspace = client.workspace.get()
print(workspace.id)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(
option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
option.WithClientCertificate("client.pem", "client.key"),
)
if err != nil {
log.Fatal(err)
}
workspace, err := client.Workspace.Get(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Println(workspace.Id)
}<?php
require __DIR__ . '/vendor/autoload.php';
$bird = new MessageBird\Bird(
getenv('BIRD_API_KEY') ?: '',
clientCert: 'client.pem',
clientKey: 'client.key',
);
echo $bird->workspace->get()->getId(), PHP_EOL;Presentar un certificado de cliente en las entregas de webhooks
Generamos un par de claves RSA 2048 y una CSR con el sujeto CN=<workspace ID>, O=Bird. La clave privada se queda en nuestros sistemas. Tu CA firma la CSR y nosotros presentamos el certificado firmado cuando tu receptor lo solicita.
Presentamos el certificado en las suscripciones de webhooks y en las devoluciones de llamada directas, incluidos los reintentos. Estas entregas no lo presentan:
- Eventos de
realtime.* - Endpoints de conectores
- Suscripciones de MCP Events
| Modo | Comportamiento de la entrega |
|---|---|
disabled | No presentamos ningún certificado. |
evaluating | Presentamos el certificado cuando el receptor lo solicita. Si el receptor lo rechaza, volvemos a entregar sin él. |
enforced | Presentamos el certificado. Si el receptor no lo solicita o lo rechaza, el intento de entrega falla. |
Firmar y subir el certificado
- Abre Webhooks > mTLS.
- En Certificate, selecciona Create signing request.
- En Signing request, selecciona Download.
- Haz que tu CA firme la CSR con el uso extendido de clave
clientAuth. - Selecciona Upload certificate.
- Pega primero el certificado firmado y después cada certificado intermedio en orden. También puedes elegir un archivo.
- Selecciona Upload certificate.
Comprobamos que el certificado coincide con la clave de la solicitud de firma, que tiene el uso extendido de clave clientAuth y que está dentro de su período de validez. A continuación, la sección Certificate muestra su sujeto, su emisor, su número de serie, su huella digital SHA-256 y su período de validez.
Configura tus receptores
- Solicita un certificado de cliente durante el protocolo de enlace TLS.
- Confía en la CA que firmó nuestro certificado.
- Presenta un certificado de servidor de una CA de confianza pública que coincida con el nombre de host del receptor.
Para aceptar nuestro certificado y ningún otro certificado de tu CA, comprueba que coincida el sujeto CN=<workspace ID> o la huella digital SHA-256.
Aplica mTLS en los webhooks
- En Mode, selecciona Evaluating y luego Save.
- Envía un evento de prueba a cada webhook con
POST /v1/webhooks/{webhook_id}/test. Comprueba queclient_certificateseapresented.not_requestedsignifica que el receptor no solicitó el certificado, yrejectedsignifica que no lo aceptó. - Para las URL de callback de SMS, que no tienen ID de webhook, envía un SMS con
options.callback_urlconfigurado con la dirección del receptor. Revisa los registros del receptor y comprueba que el callback presenta nuestro certificado. Enevaluating, un certificado rechazado también aparece enGET /v1/webhook-callbacks/attemptscomo un intento fallido con unfailure_reason. - En Mode, selecciona Enforced y luego Save.
En el modo enforced, un certificado rechazado aparece como un intento fallido en los intentos de entrega del webhook.
Comprobar la revocación
Configura Certificate revocation list check como Full chain para comprobar la revocación con listas de revocación de certificados (CRL).
- En las solicitudes de API, comprobamos el certificado de cliente y cada certificado intermedio por debajo de tu CA.
- En las entregas de webhooks, comprobamos el certificado de servidor de tu receptor y cada certificado intermedio por debajo de su raíz.
Comprobamos cada punto de distribución de CRL del certificado. Las URI http y https de un mismo punto de distribución son réplicas de la misma CRL, y usamos la primera réplica que responde. Un punto de distribución sin una URI http o https no supera la comprobación. Un certificado sin puntos de distribución de CRL no se comprueba. Verificamos la firma de cada CRL. Si no podemos obtener una CRL válida, rechazamos la solicitud o el intento de entrega falla.
| Límite | Valor |
|---|---|
| Tiempo de descarga de la CRL | 5 segundos por descarga, 10 segundos por solicitud |
| Tamaño de la CRL | 10 MiB |
| CRL por espacio de trabajo | 10 para solicitudes de API y 10 para entregas de webhooks |
Rotar certificados
Enviamos un correo electrónico a los contactos del espacio de trabajo 30 días y 7 días antes de que caduque una CA o el certificado de cliente de webhooks.
Para rotar la CA de las solicitudes de API:
- Añade la nueva CA. El espacio de trabajo pasa a confiar en ambas CA.
- Cambia cada integración a un certificado de cliente emitido por la nueva CA.
- Elimina la CA antigua.
No puedes quitar la última CA mientras el modo sea evaluating o enforced. Los certificados de cliente emitidos por tu CA no requieren ninguna acción en Bird.
Para rotar el certificado de cliente de webhooks:
- Selecciona Create new signing request.
- Haz firmar la nueva CSR y sube el certificado.
El certificado actual sigue en uso hasta que subes el nuevo. Los envíos de prueba usan el nuevo certificado de inmediato, pero las entregas pueden seguir presentando el anterior durante unos minutos. Hasta entonces, tus receptores deben aceptar ambos certificados, por CA o por huella digital.
Automatiza con la API
Cada acción del panel tiene una operación de API. Envía estas llamadas a un endpoint que acepte tu modo: el endpoint estándar en modo disabled o evaluating, y el endpoint mTLS con un certificado de cliente en modo enforced. La clave de API necesita acceso de escritura al ámbito access_restrictions. Las claves maestras de organización no pueden usar estas operaciones.
| Operación | Acción |
|---|---|
PATCH /v1/workspace/mtls-settings | Cambiar state, expected_san o crl_check |
POST /v1/workspace/mtls-certificate-authorities | Añadir una CA |
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id} | Eliminar una CA |
PATCH /v1/workspace/webhook-client-certificate | Cambiar state o crl_check |
POST /v1/workspace/webhook-client-certificate/signing-request | Crear una CSR |
POST /v1/workspace/webhook-client-certificate/certificate | Subir el certificado firmado |
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"}'Solución de problemas
Las solicitudes a API que no superan una comprobación devuelven 401 con uno de estos códigos:
| Código | Causa |
|---|---|
E02086 | La solicitud no presentó ningún certificado de cliente. |
E02087 | El certificado de cliente no es válido para el espacio de trabajo. |
E02088 | Un certificado de la cadena está revocado. |
E02089 | El modo es disabled, por lo que el endpoint mTLS rechaza la solicitud. |
E02090 | El modo es enforced, por lo que el endpoint estándar rechaza la solicitud. |
E02091 | No pudimos descargar una CRL en 5 segundos. |
E02092 | Una CRL ocupa más de 10 MiB. |
E02093 | El espacio de trabajo ya usa 10 CRL. |
E02094 | Una CRL tiene una firma no válida o ha superado su fecha de próxima actualización. |
Un cambio de configuración puede devolver uno de estos códigos:
E10027: el mTLS de API no está habilitado para el espacio de trabajo. Ponte en contacto con tu representante de Bird para habilitarlo.E10028: el mTLS de webhooks no está habilitado para el espacio de trabajo. Ponte en contacto con tu representante de Bird para habilitarlo.
Próximos pasos
- Autenticación: claves de API, ámbitos y cuentas de servicio
- Webhooks y eventos: crea endpoints y verifica firmas
- Errores: la respuesta de error y cómo gestionarla
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.