Sign inGet Started

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çãoCliente TLSServidor TLSConfigurações
Requisições APISeus sistemasO endpoint mTLSWorkspace settings > mTLS
Entregas de webhookNósSeus receptoresWebhooks > 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ãoEndpoint padrãoEndpoint mTLS
eu1https://eu1.platform.bird.comhttps://mtls.eu1.platform.bird.com
us1https://us1.platform.bird.comhttps://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.

ModoEndpoint padrãoEndpoint mTLS
disabledAceita solicitaçõesRejeita solicitações
evaluatingAceita solicitaçõesAceita solicitações com um certificado de cliente válido
enforcedRejeita solicitaçõesAceita 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áfegoModo enforced
Requisições API com uma chave de API, um token OAuth ou um token de conta de serviçoO endpoint padrão as rejeita com E02090.
Envio por SMTPRecusado. SMTP não consegue apresentar um certificado de cliente.
O servidor MCP hospedadoNão consegue acessar o espaço de trabalho, porque não pode apresentar seu certificado de cliente.
Sessões do dashboardNão são afetadas.
AutomationsNão é afetado.
Requisições com uma credencial da organização em operações da organizaçãoNão são verificadas. O modo pertence a um espaço de trabalho, e essas requisições não indicam nenhum.
Trunks SIPNã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.
  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:
Exemplo de código
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

  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.

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çãoFlagVariável de ambiente
Cadeia de certificados, PEM, começando pelo certificado final--client-certBIRD_CLIENT_CERT
Chave privada, PEM, não criptografada--client-keyBIRD_CLIENT_KEY
Enviar requisições para o endpoint mTLS--mtlsBIRD_MTLS=1
Exemplo de código
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.

// 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);

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
ModoComportamento da entrega
disabledNão apresentamos certificado.
evaluatingApresentamos o certificado quando o receptor o solicita. Se o receptor o rejeitar, entregamos novamente sem ele.
enforcedApresentamos 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.
  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. 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, 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 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 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.

LimiteValor
Tempo de download da CRL5 segundos por download, 10 segundos por requisição
Tamanho da CRL10 MiB
CRLs por espaço de trabalho10 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.

Exemplo de código
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ódigoCausa
E02086A requisição não apresentou nenhum certificado de cliente.
E02087O certificado de cliente não é válido para o espaço de trabalho.
E02088Um certificado da cadeia está revogado.
E02089O modo é disabled, então o endpoint mTLS rejeita a requisição.
E02090O modo é enforced, então o endpoint padrão rejeita a requisição.
E02091Não foi possível baixar uma CRL em até 5 segundos.
E02092Uma CRL tem mais de 10 MiB.
E02093O espaço de trabalho já usa 10 CRLs.
E02094Uma 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

Continue com a documentação, guias e exemplos sobre este tópico.