mTLS
Available on requestContact your Bird representative to enable it for your organization.
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 |
| Entregas de webhook | Nós | Seus receptores | 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_restrictionsno espaço de trabalho. Para enviar eventos de teste de webhook, obtenha também acesso de escrita ao escopowebhooks. - 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. |
| Envio por 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 | 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
- Abra Workspace settings > mTLS.
- Em Certificate authorities, selecione Add certificate authority.
- Cole o certificado PEM da sua CA ou escolha um arquivo.
- 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
- Em Mode, selecione Evaluating e depois Save.
- 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.
- Altere a URL base do seu cliente para o endpoint mTLS.
- Envie uma requisição de teste:
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 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
- Migre cada integração para o endpoint mTLS.
- 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.
O servidor MCP hospedado não consegue acessar o espaço de trabalho. Em vez dele, use o servidor MCP local da 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 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 |
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtlsPara 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.
// 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;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
- Abra Webhooks > mTLS.
- Em Certificate, selecione Create signing request.
- Em Signing request, selecione Download.
- Peça à sua CA que assine a CSR com o uso estendido de chave
clientAuth. - Selecione Upload certificate.
- Cole primeiro o certificado assinado e, em seguida, cada certificado intermediário, na ordem. Você também pode escolher um arquivo.
- 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
- Solicite um certificado de cliente durante o handshake TLS.
- Confie na CA que assinou nosso certificado.
- 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
- Em Mode, selecione Evaluating e depois selecione Save.
- Envie um evento de teste para cada webhook com
POST /v1/webhooks/{webhook_id}/test. Confirme queclient_certificateépresented.not_requestedsignifica que o receptor não solicitou o certificado, erejectedsignifica que ele não o aceitou. - Para URLs de callback de SMS, que não têm ID de webhook, envie um SMS com
options.callback_urlapontando para o receptor. Verifique os logs do receptor e confirme que o callback apresenta nosso certificado. No modoevaluating, um certificado rejeitado também aparece emGET /v1/webhook-callbacks/attemptscomo uma tentativa com falha, com umfailure_reason. - Em Mode, selecione Enforced e depois selecione Save.
No modo enforced, um certificado rejeitado aparece como uma tentativa com falha nas tentativas de entrega 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:
- Adicione a nova CA. A partir daí, o espaço de trabalho confia nas duas CAs.
- Migre cada integração para um certificado de cliente emitido pela nova CA.
- 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:
- Selecione Create new signing request.
- 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 | Alterar state, expected_san ou crl_check |
POST /v1/workspace/mtls-certificate-authorities | Adicionar uma CA |
DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id} | Remover uma CA |
PATCH /v1/workspace/webhook-client-certificate | Alterar state ou crl_check |
POST /v1/workspace/webhook-client-certificate/signing-request | Criar uma CSR |
POST /v1/workspace/webhook-client-certificate/certificate | Enviar o certificado assinado |
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 | A requisição não apresentou nenhum certificado de cliente. |
E02087 | O certificado de cliente não é válido para o espaço de trabalho. |
E02088 | Um certificado da cadeia está revogado. |
E02089 | O modo é disabled, então o endpoint mTLS rejeita a requisição. |
E02090 | O modo é enforced, então o endpoint padrão rejeita a requisição. |
E02091 | Não foi possível baixar uma CRL em até 5 segundos. |
E02092 | Uma CRL tem mais de 10 MiB. |
E02093 | O espaço de trabalho já usa 10 CRLs. |
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: 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: 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: chaves de API, escopos e contas de serviço
- Webhooks e eventos: crie endpoints e verifique assinaturas
- Erros: a resposta de erro e como tratá-la
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.