---
title: "mTLS"
description: "Exija um certificado de cliente nas requisições API por meio do endpoint mTLS e apresente um certificado de cliente nas entregas de webhook aos seus receptores."
canonical: "https://bird.com/pt-br/documentacao/guides/mtls"
availability: "on-request"
---

# mTLS

O TLS mútuo (mTLS) adiciona uma verificação de certificado ao handshake TLS nas duas direções. Cada direção tem suas próprias configurações. Você pode configurar uma direção ou ambas.

| Direção             | Cliente TLS   | Servidor TLS    | Configurações                                                                   |
| ------------------- | ------------- | --------------- | ------------------------------------------------------------------------------- |
| Requisições API     | Seus sistemas | O endpoint mTLS | [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls) |
| Entregas de webhook | Nós           | Seus receptores | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls)           |

Cada parte mantém as próprias chaves privadas. Para solicitações API, você nos envia o certificado público da sua autoridade certificadora (CA). Para entregas de webhook, nós enviamos a você uma solicitação de assinatura de certificado (CSR), e você devolve o certificado público assinado.

## Antes de começar

- Entre em contato com seu representante da Bird para habilitar o mTLS de API, o mTLS de webhook ou ambos na sua organização. Cada direção é habilitada separadamente.
- Obtenha uma função com acesso de escrita ao escopo `access_restrictions` no espaço de trabalho. Para enviar eventos de teste de webhook, obtenha também acesso de escrita ao escopo `webhooks`.
- Para requisições API, obtenha o certificado PEM da CA que emite seus certificados de cliente. Prefira a CA emissora à CA raiz: a verificação de cadeia aceita todo certificado que se encadeia a uma CA registrada, então uma CA raiz também aprova os certificados das outras CAs emissoras dela. Cada certificado ainda precisa passar pelas outras verificações, como o uso estendido de chave `clientAuth`.
- Para entregas de webhook, prepare uma CA capaz de assinar uma CSR com o uso estendido de chave `clientAuth`.

## Exija certificados de cliente em solicitações API

Cada região tem um endpoint mTLS. Ele atende às mesmas operações do endpoint padrão e solicita um certificado a cada cliente.

| Região | Endpoint padrão                 | 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` |

O certificado de cliente não substitui sua credencial. Cada requisição continua enviando uma chave de API, um token OAuth ou um token de conta de serviço no cabeçalho `Authorization`.

O modo é uma configuração do espaço de trabalho. Ele define qual endpoint aceita requisições para o espaço de trabalho com uma chave de API, um token OAuth ou um token de conta de serviço.

| Modo         | Endpoint padrão      | Endpoint mTLS                                            |
| ------------ | -------------------- | -------------------------------------------------------- |
| `disabled`   | Aceita solicitações  | Rejeita solicitações                                     |
| `evaluating` | Aceita solicitações  | Aceita solicitações com um certificado de cliente válido |
| `enforced`   | Rejeita solicitações | Aceita solicitações com um certificado de cliente válido |

O modo se aplica ao tráfego abaixo. Todo o resto continua funcionando em qualquer modo.

| Tráfego                                                                              | Modo `enforced`                                                                                            |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Requisições API com uma chave de API, um token OAuth ou um token de conta de serviço | O endpoint padrão as rejeita com [`E02090`](/docs/api/errors/E02090).                                      |
| Envio por [SMTP](/docs/guides/email/smtp)                                            | Recusado. SMTP não consegue apresentar um certificado de cliente.                                          |
| O servidor MCP hospedado                                                             | Não consegue acessar o espaço de trabalho, porque não pode apresentar seu certificado de cliente.          |
| Sessões do dashboard                                                                 | Não são afetadas.                                                                                          |
| Automations                                                                          | Não é afetado.                                                                                             |
| Requisições com uma credencial da organização em operações da organização            | Não são verificadas. O modo pertence a um espaço de trabalho, e essas requisições não indicam nenhum.      |
| [Trunks SIP](/docs/guides/voice/sip-trunks)                                          | Não são afetados. Um trunk continua autenticando chamadas com uma chave de API permitida, sem certificado. |

Uma alteração de modo vale imediatamente para novas requisições. Uma sessão SMTP aberta passa a usar o novo modo na próxima mensagem.

Um certificado de cliente válido se encadeia a uma CA do espaço de trabalho, está dentro do período de validade e tem o uso estendido de chave `clientAuth`. Se você definir um nome alternativo de entidade (SAN) obrigatório, o certificado também precisa contê-lo. Comparamos nomes DNS e URIs. Não usamos o nome comum.

### Adicione sua autoridade certificadora

1. Abra [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls).
2. Em **Certificate authorities**, selecione **Add certificate authority**.
3. Cole o certificado PEM da sua CA ou escolha um arquivo.
4. Selecione **Add certificate authority**.

O certificado precisa ter a restrição básica `CA:true` e o uso de chave `keyCertSign`, e não pode estar expirado. Um espaço de trabalho pode ter duas CAs.

Se a sua CA também emite certificados para terceiros, defina **Required subject alternative name** com a identidade que seus certificados de cliente contêm.

### Teste no modo de avaliação

1. Em **Mode**, selecione **Evaluating** e depois **Save**.
2. Configure seu cliente para apresentar o certificado dele. Se uma CA intermediária assinar o certificado de cliente, envie também o certificado intermediário.
3. Altere a URL base do seu cliente para o endpoint mTLS.
4. Envie uma requisição de teste:

```bash
curl https://mtls.eu1.platform.bird.com/v1/workspace \
  --cert client.pem \
  --key client.key \
  -H "Authorization: Bearer $BIRD_API_KEY"
```

Uma resposta diferente de `401` indica que a verificação do certificado foi aprovada. Uma resposta `401` contém um código de erro. A seção [Solução de problemas](#solução-de-problemas) informa a causa de cada código.

Para encontrar os chamadores que o modo `enforced` recusaria, filtre os logs de requisições do espaço de trabalho por **mTLS** `missing`. Os logs de requisições registram operações de escrita, como requisições `POST`, `PATCH` e `DELETE`, e envios por SMTP. Eles não registram leituras, então verifique separadamente os clientes que só fazem leituras: o modo `enforced` também os recusa.

### Exija o mTLS

1. Migre cada integração para o endpoint mTLS.
2. Em **Mode**, selecione **Enforced** e depois selecione **Save**.

A partir daí, o endpoint padrão rejeita as requisições com uma chave de API, um token OAuth ou um token de conta de serviço do espaço de trabalho, retornando [`E02090`](/docs/api/errors/E02090).

O servidor MCP hospedado não consegue acessar o espaço de trabalho. Em vez dele, use o servidor MCP local da [Bird CLI](#use-a-bird-cli).

O endpoint SMTP recusa o AUTH para o espaço de trabalho com `535 5.7.8`. Uma sessão SMTP aberta recebe `530 5.7.0` na próxima mensagem. Em vez disso, envie e-mails pela API no endpoint mTLS.

Uma alteração nas CAs ou na SAN obrigatória pode levar até 15 minutos para valer em cada requisição.

### Use a Bird CLI

A [Bird CLI](/docs/cli) e o servidor MCP local dela (`bird mcp`) apresentam seu certificado de cliente com estas configurações:

| Configuração                                                  | Flag            | Variável de ambiente |
| ------------------------------------------------------------- | --------------- | -------------------- |
| Cadeia de certificados, PEM, começando pelo certificado final | `--client-cert` | `BIRD_CLIENT_CERT`   |
| Chave privada, PEM, não criptografada                         | `--client-key`  | `BIRD_CLIENT_KEY`    |
| Enviar requisições para o 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 manter as configurações com um login OAuth, passe as três flags para `bird auth login`. O perfil armazena os caminhos dos arquivos, e os comandos seguintes usam o endpoint mTLS sem flags. `bird auth status` mostra a impressão digital SHA-256 e o vencimento do certificado.

### Use um SDK

Informe ao SDK os caminhos da sua cadeia de certificados (PEM, começando pelo certificado final) e da chave privada dela (PEM, não criptografada). O SDK apresenta o certificado em toda requisição e envia as requisições para o endpoint mTLS da região da sua chave de API. Se você definir uma URL base, o SDK usa essa URL.

O SDK recusa um certificado junto com um cliente HTTP fornecido por você. Para usar seu próprio cliente HTTP, configure o certificado nesse cliente e defina a URL base como o 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](/pt-br/documentacao/guides/mtls.ts.md) · [Python](/pt-br/documentacao/guides/mtls.py.md) · [Go](/pt-br/documentacao/guides/mtls.go.md) · [PHP](/pt-br/documentacao/guides/mtls.php.md)

## Apresente um certificado de cliente nas entregas de webhook

Geramos um par de chaves RSA 2048 e uma CSR com o assunto `CN=<workspace ID>, O=Bird`. A chave privada fica conosco. Sua CA assina a CSR, e apresentamos o certificado assinado quando seu receptor solicita um.

Apresentamos o certificado nas assinaturas de webhook e nos callbacks diretos, incluindo as novas tentativas. Estas entregas não o apresentam:

- Eventos de `realtime.*`
- Endpoints de conectores
- Assinaturas do MCP Events

| Modo         | Comportamento da entrega                                                                                         |
| ------------ | ---------------------------------------------------------------------------------------------------------------- |
| `disabled`   | Não apresentamos certificado.                                                                                    |
| `evaluating` | Apresentamos o certificado quando o receptor o solicita. Se o receptor o rejeitar, entregamos novamente sem ele. |
| `enforced`   | Apresentamos o certificado. Se o receptor não o solicitar ou o rejeitar, a tentativa de entrega falha.           |

### Assine e envie o certificado

1. Abra [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls).
2. Em **Certificate**, selecione **Create signing request**.
3. Em **Signing request**, selecione **Download**.
4. Peça à sua CA que assine a CSR com o uso estendido de chave `clientAuth`.
5. Selecione **Upload certificate**.
6. Cole primeiro o certificado assinado e, em seguida, cada certificado intermediário, na ordem. Você também pode escolher um arquivo.
7. Selecione **Upload certificate**.

Verificamos se o certificado corresponde à chave da solicitação de assinatura, se tem o uso estendido de chave `clientAuth` e se está dentro do período de validade. Em seguida, a seção **Certificate** mostra o assunto, o emissor, o número de série, a impressão digital SHA-256 e o período de validade do certificado.

### Configure seus receptores

1. Solicite um certificado de cliente durante o handshake TLS.
2. Confie na CA que assinou nosso certificado.
3. Apresente um certificado de servidor emitido por uma CA publicamente confiável e que corresponda ao nome de host do receptor.

Para aceitar nosso certificado e nenhum outro certificado da sua CA, compare o assunto `CN=<workspace ID>` ou a impressão digital SHA-256.

### Exija mTLS nos webhooks

1. Em **Mode**, selecione **Evaluating** e depois selecione **Save**.
2. Envie um evento de teste para cada webhook com [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook). Confirme que `client_certificate` é `presented`. `not_requested` significa que o receptor não solicitou o certificado, e `rejected` significa que ele não o aceitou.
3. Para [URLs de callback de SMS](/docs/guides/sms/callbacks), que não têm ID de webhook, envie um SMS com `options.callback_url` apontando para o receptor. Verifique os logs do receptor e confirme que o callback apresenta nosso certificado. No modo `evaluating`, um certificado rejeitado também aparece em [`GET /v1/webhook-callbacks/attempts`](/docs/api/reference/list-webhook-callback-attempts) como uma tentativa com falha, com um `failure_reason`.
4. Em **Mode**, selecione **Enforced** e depois selecione **Save**.

No modo `enforced`, um certificado rejeitado aparece como uma tentativa com falha nas [tentativas de entrega](/docs/guides/webhooks#replaying-failed-deliveries) do webhook.

## Verificar a revogação

Defina **Certificate revocation list check** como **Full chain** para verificar a revogação com listas de revogação de certificados (CRLs).

- Nas requisições API, verificamos o certificado do cliente e cada certificado intermediário abaixo da sua CA.
- Nas entregas de webhook, verificamos o certificado de servidor do seu receptor e cada certificado intermediário abaixo da raiz dele.

Verificamos cada ponto de distribuição de CRL do certificado. As URIs `http` e `https` de um mesmo ponto de distribuição são espelhos da mesma CRL, e usamos o primeiro espelho que responder. Um ponto de distribuição sem URI `http` ou `https` falha na verificação. Um certificado sem pontos de distribuição de CRL não é verificado. Verificamos a assinatura de cada CRL. Se não conseguirmos obter uma CRL válida, rejeitamos a requisição ou a tentativa de entrega falha.

| Limite                      | Valor                                                 |
| --------------------------- | ----------------------------------------------------- |
| Tempo de download da CRL    | 5 segundos por download, 10 segundos por requisição   |
| Tamanho da CRL              | 10 MiB                                                |
| CRLs por espaço de trabalho | 10 para requisições API e 10 para entregas de webhook |

## Rotacionar certificados

Enviamos um e-mail aos contatos do espaço de trabalho 30 dias e 7 dias antes do vencimento de uma CA ou do certificado de cliente do webhook.

Para rotacionar a CA das requisições API:

1. Adicione a nova CA. A partir daí, o espaço de trabalho confia nas duas CAs.
2. Migre cada integração para um certificado de cliente emitido pela nova CA.
3. Remova a CA antiga.

Não é possível remover a última CA enquanto o modo for `evaluating` ou `enforced`. Os certificados de cliente emitidos pela sua CA não exigem nenhuma ação em Bird.

Para fazer a rotação do certificado de cliente de webhook:

1. Selecione **Create new signing request**.
2. Obtenha a assinatura da nova CSR e faça o upload do certificado.

O certificado atual continua em uso até você fazer o upload do novo. Os envios de teste usam o novo certificado imediatamente, mas as entregas podem continuar apresentando o anterior por até alguns minutos. Até lá, seus receptores precisam aceitar os dois certificados, pela CA ou pela impressão digital.

## Automatize com a API

Cada ação do dashboard tem uma operação na API. Envie essas chamadas para um endpoint que o seu modo aceite: o endpoint padrão no modo `disabled` ou `evaluating`, e o endpoint mTLS com um certificado de cliente no modo `enforced`. A chave de API precisa de acesso de escrita ao escopo `access_restrictions`. As chaves mestras da organização não podem usar essas operações.

| Operação                                                                                                                                           | Ação                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [`PATCH /v1/workspace/mtls-settings`](/docs/api/reference/update-workspace-mtls-settings)                                                          | Alterar `state`, `expected_san` ou `crl_check` |
| [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority)                               | Adicionar uma CA                               |
| [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority)  | Remover uma CA                                 |
| [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate)                                | Alterar `state` ou `crl_check`                 |
| [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | Criar uma CSR                                  |
| [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate)                     | Enviar o certificado assinado                  |

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

## Solução de problemas

As requisições API que falham em uma verificação retornam `401` com um destes códigos:

| Código                              | Causa                                                                               |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| [`E02086`](/docs/api/errors/E02086) | A requisição não apresentou nenhum certificado de cliente.                          |
| [`E02087`](/docs/api/errors/E02087) | O certificado de cliente não é válido para o espaço de trabalho.                    |
| [`E02088`](/docs/api/errors/E02088) | Um certificado da cadeia está revogado.                                             |
| [`E02089`](/docs/api/errors/E02089) | O modo é `disabled`, então o endpoint mTLS rejeita a requisição.                    |
| [`E02090`](/docs/api/errors/E02090) | O modo é `enforced`, então o endpoint padrão rejeita a requisição.                  |
| [`E02091`](/docs/api/errors/E02091) | Não foi possível baixar uma CRL em até 5 segundos.                                  |
| [`E02092`](/docs/api/errors/E02092) | Uma CRL tem mais de 10 MiB.                                                         |
| [`E02093`](/docs/api/errors/E02093) | O espaço de trabalho já usa 10 CRLs.                                                |
| [`E02094`](/docs/api/errors/E02094) | Uma CRL tem uma assinatura inválida ou já passou do horário da próxima atualização. |

Uma alteração de configuração pode retornar um destes códigos:

- [`E10027`](/docs/api/errors/E10027): o mTLS de API não está habilitado para o espaço de trabalho. Entre em contato com seu representante da Bird para habilitá-lo.
- [`E10028`](/docs/api/errors/E10028): o mTLS de webhook não está habilitado para o espaço de trabalho. Entre em contato com seu representante da Bird para habilitá-lo.

## Próximos passos

- [Autenticação](/docs/guides/authentication): chaves de API, escopos e contas de serviço
- [Webhooks e eventos](/docs/guides/webhooks): crie endpoints e verifique assinaturas
- [Erros](/docs/guides/errors): a resposta de erro e como tratá-la

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