DEV Community

Cover image for Como Testar APIs com mTLS (Certificados do Cliente) no Apidog
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Testar APIs com mTLS (Certificados do Cliente) no Apidog

Você acessa uma API de parceiro, envia uma requisição bem-formada com um token válido e, ainda assim, recebe uma falha no handshake TLS. Nesse caso, o endpoint não está pedindo sua chave de API: ele está exigindo que o cliente prove sua identidade com um certificado antes que qualquer requisição HTTP saia da sua máquina. Isso é TLS mútuo (mTLS).

Experimente o Apidog hoje

Neste guia, você vai configurar certificados de cliente e certificados CA no Apidog para testar APIs protegidas por mTLS. Você aprenderá a vincular um certificado e uma chave privada a um host, adicionar uma CA para confiar em certificados autoassinados e enviar requisições que o Apidog assina automaticamente durante o handshake. Se certificados ainda são novidade para você, leia também o guia sobre verificação de certificado SSL. Para entender o protocolo, consulte a referência TLS da MDN.

O que é TLS mútuo e por que algumas APIs o exigem

No HTTPS tradicional, a confiança é unilateral:

  1. O servidor apresenta um certificado.
  2. O cliente verifica esse certificado.
  3. A conexão é criptografada.

O servidor não recebe uma prova criptográfica da identidade do cliente. Normalmente, ele depende de um token, chave de API ou credencial enviada na requisição.

No TLS mútuo, a validação acontece nos dois sentidos:

  1. O servidor apresenta seu certificado.
  2. O cliente valida o certificado do servidor.
  3. O servidor solicita um certificado ao cliente.
  4. O cliente apresenta seu certificado e prova que possui a chave privada correspondente.
  5. O servidor valida esse certificado antes de abrir a conexão.

Se o certificado do cliente não for confiável para o servidor, o handshake falha. Nenhum cabeçalho, corpo ou token HTTP é enviado.

Você encontrará mTLS principalmente nestes cenários:

  • Bancos e pagamentos: APIs de open banking e processadores de cartão podem exigir certificado de cliente além de OAuth. A documentação do Stripe descreve modelos de credenciais em camadas para endpoints financeiros sensíveis.
  • Tráfego interno entre serviços: arquiteturas de confiança zero usam certificados para identificar serviços, em vez de depender apenas do perímetro da rede.
  • APIs B2B: parceiros podem emitir certificados durante o onboarding para limitar o acesso a máquinas ou organizações autorizadas.

Se OAuth também estiver em uso, as duas camadas funcionam juntas. A RFC 8705 define como vincular tokens OAuth a certificados de cliente em mTLS.

No Apidog, mantenha esta separação clara:

Camada Configuração no Apidog
Identidade TLS e mTLS Certificados
Chaves de API, Bearer Token, OAuth e Basic Auth Autorização

Em muitas integrações, você precisará configurar os dois.

Como o Apidog aplica certificados por host

No Apidog, certificados de cliente e certificados CA são configurados globalmente. Você registra o certificado uma vez, associa-o a um host e o Apidog o aplica automaticamente às requisições HTTPS compatíveis.

Há dois tipos de certificado:

  • Certificado de cliente: é enviado ao servidor para provar a identidade do cliente durante o mTLS.
  • Certificado CA: adiciona uma autoridade certificadora à lista de CAs confiáveis pelo Apidog. Ele é útil para CAs internas, certificados autoassinados e ambientes de staging.

Por exemplo, um certificado CA pode resolver este erro:

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

O ponto principal é a correspondência por host. Se o host configurado não corresponder ao host da URL, o Apidog não enviará o certificado de cliente.

Configurar um certificado de cliente para uma API mTLS

Considere este cenário:

  • O parceiro é partner-api.acmebank.com.
  • Durante o onboarding, ele forneceu um certificado de cliente e uma chave privada.
  • A API exige mTLS.
  • Você quer chamar GET /v1/settlements.

Passo 1: abra as configurações de Certificados

No Apidog:

  1. Clique no ícone de configurações no canto superior direito.
  2. Abra a aba Certificados.

Essa configuração não pertence a uma requisição específica. O Apidog a reutiliza em todas as requisições HTTPS cujo host corresponda à regra definida.

Passo 2: adicione o certificado de cliente

Na seção Certificados de Cliente:

  1. Clique em Adicionar Certificado.
  2. Informe o host.
  3. Selecione os arquivos do certificado.

No campo Host, informe apenas o domínio:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Não inclua https://.

Se o mesmo certificado cobrir diversos subdomínios, use um padrão curinga:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Isso permite reutilizar o certificado para hosts como:

partner-api.acmebank.com
sandbox-api.acmebank.com
settlements-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

A porta é opcional. Se você não informar uma porta, o Apidog usa 443.

Informe uma porta personalizada somente quando necessário, por exemplo:

8443
Enter fullscreen mode Exit fullscreen mode

Passo 3: selecione os arquivos do certificado

O Apidog aceita dois formatos comuns para certificados de cliente:

  • CRT + Chave: certificado e chave privada em arquivos separados.
  • PFX: um arquivo único que contém certificado e chave privada.

Exemplos de arquivos que você pode receber:

client.crt
client.key
Enter fullscreen mode Exit fullscreen mode

Ou:

client.pfx
Enter fullscreen mode Exit fullscreen mode

Se a chave privada ou o arquivo PFX estiver protegido por senha, informe-a no campo Senha. Caso contrário, deixe o campo vazio.

Passo 4: salve a configuração

Clique em Adicionar.

O certificado ficará vinculado ao host configurado, por exemplo:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

A partir daí, você não precisa anexar o certificado manualmente em cada requisição.

Passo 5: envie uma requisição autenticada

Crie a requisição:

GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>
Enter fullscreen mode Exit fullscreen mode

Ao enviar:

  1. O Apidog identifica o host da URL.
  2. Encontra o certificado de cliente correspondente.
  3. Apresenta esse certificado durante o handshake TLS.
  4. Conclui o mTLS.
  5. Envia a requisição HTTP com o token OAuth, se necessário.

O certificado prova a identidade do cliente na camada TLS. O token prova a identidade ou permissão na camada da aplicação.

Uma resposta de exemplo:

{
  "settlements": [
    {
      "id": "stl_88213",
      "amount": 41200,
      "currency": "USD",
      "status": "cleared",
      "settled_at": "2026-07-14T09:31:00Z"
    }
  ],
  "next_cursor": null
}
Enter fullscreen mode Exit fullscreen mode

Adicionar um certificado CA para raízes internas ou autoassinadas

O certificado de cliente resolve apenas uma parte do problema: ele permite que o servidor confie em você.

Também é necessário que o Apidog confie no servidor.

Em ambientes internos, staging ou redes corporativas, o certificado do servidor pode ser assinado por uma CA privada. Nesses casos, a requisição pode falhar antes do mTLS com uma mensagem como:

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

Para resolver:

  1. Abra a aba Certificados.
  2. Ative a opção em Certificados CA.
  3. Selecione o arquivo PEM da sua CA.

Um arquivo PEM pode conter mais de um certificado, incluindo raízes e intermediários:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
Enter fullscreen mode Exit fullscreen mode

Depois de adicionar a CA, o Apidog passa a confiar nos servidores assinados por ela.

Em um ambiente interno com mTLS, você normalmente precisa dos dois componentes:

  • Certificado CA: para confiar no servidor.
  • Certificado de cliente: para o servidor confiar em você.

Dicas práticas e variações comuns

Use curingas para subdomínios

Se o parceiro forneceu um certificado válido para vários subdomínios, configure:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Assim, você evita criar uma entrada para cada endpoint.

Configure portas não padrão

Gateways internos frequentemente usam portas como:

8443
9443
Enter fullscreen mode Exit fullscreen mode

Se o endpoint estiver em uma porta diferente de 443, configure essa porta no certificado. Caso contrário, o host não corresponderá corretamente e o certificado não será enviado.

Certificados não são editáveis após serem adicionados

Não há edição direta para certificados já registrados.

Para corrigir um host, trocar a chave privada ou renovar um certificado:

  1. Remova a entrada antiga usando o ícone de exclusão.
  2. Adicione o novo certificado.

Inclua esse processo no seu procedimento de rotação de certificados.

Use apenas um certificado por domínio

Evite cadastrar dois certificados de cliente para o mesmo domínio. Isso cria ambiguidade sobre qual certificado o Apidog deve apresentar.

Mantenha uma única configuração por host ou padrão de host.

Não misture Certificados e Autorização

A configuração correta é:

  • Certificados: mTLS, certificado de cliente, chave privada e CA.
  • Autorização: API Key, Bearer Token, OAuth e Basic Auth.

A autorização pode ser aplicada em vários níveis:

  • Requisição individual.
  • Pasta.
  • Coleção.

As requisições podem herdar a autorização configurada na pasta ou coleção.

Se sua API exige certificado de cliente e OAuth:

  1. Configure o certificado em Certificados.
  2. Configure o token OAuth em Autorização.

Para aprofundar a configuração de tokens, consulte o guia sobre autenticação de gateway de API. Para cenários Windows com autenticação corporativa, veja como configurar a autenticação Kerberos no Apidog.

mTLS exige HTTPS

O Apidog não envia certificados de cliente em requisições HTTP simples.

Isto não ativa mTLS:

http://partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Use HTTPS:

https://partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

Automatize o fluxo de trabalho com o CLI do Apidog

Depois de validar manualmente suas requisições mTLS, adicione os testes a cenários salvos e execute-os no CI/CD com o CLI do Apidog.

Instale o CLI e autentique-se:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Execute um cenário salvo em um ambiente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

O comando apidog run suporta certificados diretamente:

Opção Uso
--ssl-client-cert Certificado do cliente em PEM
--ssl-client-key Chave privada do cliente
--ssl-client-passphrase Senha da chave privada, quando existir
--ssl-extra-ca-certs CAs adicionais confiáveis
--ssl-client-cert-list Arquivo de configuração para associar certificados a padrões de URL

Você também pode definir múltiplos reportadores:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

Adicione esse comando ao pipeline para executar testes de APIs protegidas por certificado a cada push. Veja o guia de CLI do Apidog em CI/CD para configurar essa etapa no pipeline.

Perguntas frequentes

Preciso de certificado de cliente e certificado CA?

Depende do endpoint.

Você precisa de um certificado de cliente sempre que o servidor exigir mTLS.

Você precisa de um certificado CA quando o certificado do servidor foi assinado por uma autoridade que sua máquina ainda não reconhece, como uma CA interna.

Uma API pública com certificado emitido por uma CA pública confiável normalmente exige apenas o certificado de cliente. Um serviço interno protegido por mTLS pode exigir os dois.

Por que o Apidog não está enviando meu certificado de cliente?

Verifique estes pontos:

  • O campo Host contém apenas o domínio, sem https://.
  • O host configurado corresponde ao host da URL.
  • A porta corresponde à do endpoint.
  • A URL usa https://.
  • Você não está tentando usar mTLS em uma requisição http://.

O Apidog nunca anexa um certificado de cliente a uma requisição HTTP simples.

Onde configuro chaves de API e Bearer Tokens?

Configure-os na aba Autorização da requisição, pasta ou coleção.

Use Certificados para identidade na camada TLS e Autorização para credenciais da camada HTTP.

Veja a lista completa de opções no guia sobre esquemas de segurança.

Um certificado pode cobrir vários subdomínios?

Sim. Use um padrão curinga no campo de host:

*.example.com
Enter fullscreen mode Exit fullscreen mode

O certificado será aplicado aos subdomínios de example.com.

Como atualizo um certificado?

Os certificados não podem ser editados diretamente.

Remova a configuração existente e adicione o certificado corrigido ou renovado. Para organizar outros valores reutilizáveis de testes, veja como definir parâmetros globais no Apidog.

Conclusão

Para testar uma API protegida por mTLS no Apidog:

  1. Vincule o certificado de cliente ao host correto.
  2. Adicione um certificado CA se o servidor usar uma raiz privada ou autoassinada.
  3. Envie requisições HTTPS para que o Apidog aplique automaticamente o certificado correspondente.
  4. Configure OAuth, API Keys e tokens separadamente na aba Autorização.

Com essa separação, o handshake TLS deixa de ser uma etapa misteriosa e passa a fazer parte do fluxo normal de testes.

Baixe o Apidog, adicione o certificado do parceiro e envie sua primeira requisição autenticada.

Top comments (0)