---
title: "mTLS"
description: "Exige un certificado de cliente en las solicitudes a API a través del endpoint mTLS y presenta un certificado de cliente en las entregas de webhooks a tus receptores."
canonical: "https://bird.com/es-es/documentacion/guides/mtls"
availability: "on-request"
---

# mTLS

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**](https://bird.com/dashboard/w/settings/mtls) |
| Entregas de webhooks | Nosotros     | Tus receptores   | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/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_restrictions` en el espacio de trabajo. Para enviar eventos de prueba de webhooks, consigue también acceso de escritura al ámbito `webhooks`.
- 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`](/docs/api/errors/E02090).                                         |
| Envío de [SMTP](/docs/guides/email/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](/docs/guides/voice/sip-trunks)                                          | 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

1. Abre [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls).
2. En **Certificate authorities**, selecciona **Add certificate authority**.
3. Pega el certificado PEM de tu CA o elige un archivo.
4. 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

1. En **Mode**, selecciona **Evaluating** y, después, **Save**.
2. Configura tu cliente para que presente su certificado. Si una CA intermedia firma el certificado de cliente, envía también el certificado intermedio.
3. Cambia la URL base de tu cliente al endpoint mTLS.
4. Envía una solicitud de prueba:

```bash
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](#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

1. Migra cada integración al endpoint mTLS.
2. 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`](/docs/api/errors/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](#usa-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](/docs/cli) 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`       |

```bash
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtls
```

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

**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](/es-es/documentacion/guides/mtls.ts.md) · [Python](/es-es/documentacion/guides/mtls.py.md) · [Go](/es-es/documentacion/guides/mtls.go.md) · [PHP](/es-es/documentacion/guides/mtls.php.md)

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

1. Abre [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls).
2. En **Certificate**, selecciona **Create signing request**.
3. En **Signing request**, selecciona **Download**.
4. Haz que tu CA firme la CSR con el uso extendido de clave `clientAuth`.
5. Selecciona **Upload certificate**.
6. Pega primero el certificado firmado y después cada certificado intermedio en orden. También puedes elegir un archivo.
7. 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

1. Solicita un certificado de cliente durante el protocolo de enlace TLS.
2. Confía en la CA que firmó nuestro certificado.
3. 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

1. En **Mode**, selecciona **Evaluating** y luego **Save**.
2. Envía un evento de prueba a cada webhook con [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook). Comprueba que `client_certificate` sea `presented`. `not_requested` significa que el receptor no solicitó el certificado, y `rejected` significa que no lo aceptó.
3. Para las [URL de callback de SMS](/docs/guides/sms/callbacks), que no tienen ID de webhook, envía un SMS con `options.callback_url` configurado con la dirección del receptor. Revisa los registros del receptor y comprueba que el callback presenta nuestro certificado. En `evaluating`, un certificado rechazado también aparece en [`GET /v1/webhook-callbacks/attempts`](/docs/api/reference/list-webhook-callback-attempts) como un intento fallido con un `failure_reason`.
4. En **Mode**, selecciona **Enforced** y luego **Save**.

En el modo `enforced`, un certificado rechazado aparece como un intento fallido en los [intentos de entrega](/docs/guides/webhooks#replaying-failed-deliveries) 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:

1. Añade la nueva CA. El espacio de trabajo pasa a confiar en ambas CA.
2. Cambia cada integración a un certificado de cliente emitido por la nueva CA.
3. 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:

1. Selecciona **Create new signing request**.
2. 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`](/docs/api/reference/update-workspace-mtls-settings)                                                          | Cambiar `state`, `expected_san` o `crl_check` |
| [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority)                               | Añadir una CA                                 |
| [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority)  | Eliminar una CA                               |
| [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate)                                | Cambiar `state` o `crl_check`                 |
| [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | Crear una CSR                                 |
| [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate)                     | Subir el certificado firmado                  |

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

## 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`](/docs/api/errors/E02086) | La solicitud no presentó ningún certificado de cliente.                            |
| [`E02087`](/docs/api/errors/E02087) | El certificado de cliente no es válido para el espacio de trabajo.                 |
| [`E02088`](/docs/api/errors/E02088) | Un certificado de la cadena está revocado.                                         |
| [`E02089`](/docs/api/errors/E02089) | El modo es `disabled`, por lo que el endpoint mTLS rechaza la solicitud.           |
| [`E02090`](/docs/api/errors/E02090) | El modo es `enforced`, por lo que el endpoint estándar rechaza la solicitud.       |
| [`E02091`](/docs/api/errors/E02091) | No pudimos descargar una CRL en 5 segundos.                                        |
| [`E02092`](/docs/api/errors/E02092) | Una CRL ocupa más de 10 MiB.                                                       |
| [`E02093`](/docs/api/errors/E02093) | El espacio de trabajo ya usa 10 CRL.                                               |
| [`E02094`](/docs/api/errors/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`](/docs/api/errors/E10027): el mTLS de API no está habilitado para el espacio de trabajo. Ponte en contacto con tu representante de Bird para habilitarlo.
- [`E10028`](/docs/api/errors/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](/docs/guides/authentication): claves de API, ámbitos y cuentas de servicio
- [Webhooks y eventos](/docs/guides/webhooks): crea endpoints y verifica firmas
- [Errores](/docs/guides/errors): la respuesta de error y cómo gestionarla

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