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 é atingido por uma falha de handshake TLS. O endpoint não está pedindo sua chave de API. Ele está pedindo que seu cliente prove quem ele é com um certificado, antes mesmo que qualquer requisição HTTP saia da sua máquina. Isso é TLS mútuo, e se você nunca o configurou em uma ferramenta de teste, pode atrasar uma integração por um dia.

Este guia explica como configurar certificados de cliente e certificados CA no Apidog para que você possa testar uma API protegida por mTLS sem lutar contra o handshake. Você adicionará um certificado e chave de cliente para um host específico, anexará um certificado CA para que raízes autoassinadas parem de gerar erros e enviará uma requisição autenticada que o Apidog assinará automaticamente. Se erros de certificado são um território novo, o guia introdutório sobre verificação de certificado SSL vale a pena ler junto com este. Para o protocolo em si, a referência TLS da MDN é uma explicação sólida e neutra em relação ao fornecedor.

botão

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

O HTTPS regular é uma confiança unilateral. O servidor apresenta um certificado, seu cliente o verifica e a conexão é criptografada. O servidor não tem prova criptográfica de quem você é; ele depende de um token ou chave de API dentro da requisição para isso.

O TLS mútuo faz a confiança ir nos dois sentidos. O servidor ainda apresenta seu certificado, mas também pede ao cliente para apresentar um. Se o seu certificado não for assinado por uma autoridade de certificação em que o servidor confia, o handshake falha e a conexão nunca é aberta. Nenhum corpo de requisição, nenhum cabeçalho, nada passa.

Você encontrará a autenticação TLS mútuo (mTLS) em locais onde um token de portador vazado não é um modo de falha aceitável:

Bancos e pagamentos. APIs de open banking e processadores de cartão frequentemente exigem um certificado de cliente emitido para sua organização, além do OAuth. A documentação do Stripe descreve esse tipo de modelo de credencial em camadas para endpoints financeiros sensíveis.
Tráfego interno e entre serviços. Empresas que operam uma rede de confiança zero fazem com que os serviços provem sua identidade com certificados em vez de confiar no perímetro da rede.
APIs de parceiros B2B. Um parceiro pode emitir um certificado de cliente durante o onboarding para que apenas suas máquinas registradas possam acessar seus endpoints.

Se o OAuth também estiver em uso, os dois se combinam de forma limpa; a RFC 8705 formaliza como o TLS mútuo vincula um token OAuth a um certificado de cliente. O certificado é uma credencial da camada de rede, separada da autenticação da camada de aplicação em sua requisição. Essa distinção é importante no Apidog e é o que as pessoas mais se confundem. Os Certificados lidam com mTLS. A aba Autorização lida com chaves de API, tokens de portador, OAuth e autenticação Básica. Você frequentemente precisa de ambos ao mesmo tempo, mas os configura em lugares diferentes.

Como o Apidog define o escopo dos certificados por host

O Apidog lida com certificados CA e certificados de cliente, e os configura globalmente em vez de por requisição. Você configura um certificado uma vez, o vincula a um host, e o Apidog o anexa automaticamente em cada requisição HTTPS que corresponda a esse host. Não há um botão por requisição para lembrar e nenhum cabeçalho para colar.

Dois tipos de certificado realizam dois trabalhos diferentes:

Um certificado de cliente é o que você apresenta para provar sua identidade para autenticação TLS mútuo. É a credencial que a API do parceiro solicita.
Um certificado CA informa ao Apidog para confiar em uma autoridade de certificação que ele ainda não conhece. Aponte-o para sua CA raiz interna e o temido SSL Error: Self signed certificate desaparece, porque o Apidog agora confia em endpoints assinados por essa autoridade.

A chave de escopo é o host. Cada certificado de cliente está vinculado a um domínio, e o Apidog compara o host da requisição de saída com essa vinculação. Acertando o host, todo o resto é automático. Erre, e o Apidog silenciosamente não envia nada, porque nunca encontrou uma correspondência.

Configurar um certificado de cliente para uma API mTLS

Aqui está o cenário. Um parceiro de pagamentos, partner-api.acmebank.com, emitiu um certificado de cliente e uma chave privada durante o onboarding. A API deles é apenas HTTPS e rejeita qualquer cliente que não possa apresentar esse certificado. Você deseja chamar GET /v1/settlements e inspecionar a resposta.

Passo 1: Abra as configurações de Certificados

Abra as configurações do Apidog usando o ícone de configurações no canto superior direito e vá para a aba Certificados. É aqui que ambos os tipos de certificado residem. Nada aqui está vinculado a uma única requisição; ele se aplica a todas as suas requisições com base na correspondência do host.

Passo 2: Adicione o certificado de cliente

Em Certificados de Cliente, selecione Adicionar Certificado. Um formulário será aberto para a vinculação do host e os arquivos de certificado.

Preencha o campo Host apenas com o domínio, sem protocolo:

partner-api.acmebank.com

Deixe de fora https://. O campo aceita um domínio nu. Se você precisar de um certificado para cobrir vários subdomínios, o campo host suporta correspondência de padrões. Inserir *.acmebank.com usa o mesmo certificado de cliente para cada subdomínio em acmebank.com, o que é útil quando um parceiro executa partner-api, sandbox-api e settlements-api com o mesmo certificado emitido.

A porta personalizada é opcional. Deixe-a em branco e o Apidog usará 443 por padrão, a porta HTTPS padrão. Defina uma porta apenas se o endpoint mTLS escutar em outro lugar, por exemplo 8443.

Passo 3: Selecione os arquivos de certificado

O Apidog aceita dois layouts de arquivo para um certificado de cliente. Escolha o que seu parceiro lhe deu:

Arquivos CRT + Chave. Um arquivo de certificado e um arquivo de chave privada separados. Selecione cada um em seu respectivo campo.
Arquivos PFX. Um único arquivo agrupado que empacota o certificado e a chave juntos.

Se o certificado foi gerado com uma senha, insira-a no campo senha. É opcional, então deixe-o vazio se sua chave não for protegida por senha. Um pacote de onboarding típico de um banco vem como um par .crt e .key, às vezes com uma senha na chave.

Passo 4: Salve

Selecione Adicionar para salvar o certificado de cliente. Ele agora aparece em sua lista, vinculado a partner-api.acmebank.com. A partir deste ponto, você não precisa mais tocá-lo por requisição.

Passo 5: Envie a requisição autenticada

Crie uma requisição para o host e envie-a:

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

O Apidog compara o host, anexa seu certificado de cliente durante o handshake TLS e completa a autenticação TLS mútuo antes que a requisição seja enviada. Se o parceiro também exigir OAuth, esse token de portador acompanha a requisição como de costume. O certificado prova a máquina; o token prova o chamador. Uma resposta bem-sucedida pode se parecer com isto:

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

Nenhum passo manual por requisição fez isso acontecer. A correspondência do host fez.

Adicionar um certificado CA para raízes internas ou autoassinadas

Certificados de cliente são metade da história. A outra metade aparece quando o próprio certificado do servidor é assinado por uma autoridade em que sua máquina não confia, comum em serviços internos e ambientes de staging que usam uma CA raiz privada.

Quando isso acontece, a requisição falha com uma mensagem como SSL Error: Self signed certificate antes mesmo que o mTLS tenha uma chance. A solução é fornecer a CA ao Apidog para que ele confie nessa raiz.

Na mesma aba Certificados, ative a opção ao lado de Certificados CA e, em seguida, selecione seu arquivo PEM. Os certificados CA usam o formato PEM, e um único arquivo PEM pode conter vários certificados CA, então você pode agrupar uma cadeia inteira de raízes e intermediários internos em um único arquivo:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----

Uma vez que a CA é confiável, o Apidog para de rejeitar endpoints assinados por ela. Emparelhe uma CA confiável com um certificado de cliente e você poderá testar um serviço mTLS interno que usa uma raiz privada de ponta a ponta: a CA permite que você confie no servidor deles, e o certificado de cliente permite que eles confiem em você.

Dicas avançadas e variações comuns

Algumas coisas economizam tempo depois que você passa pela configuração básica.

Cobertura de subdomínio com um certificado. Se um parceiro emitiu um certificado com escopo curinga, defina o host como *.acmebank.com uma vez, em vez de registrar partner-api, sandbox-api e o restante separadamente. Uma vinculação, todos os subdomínios.

Portas não padrão. Gateways mTLS internos adoram portas como 8443 ou 9443. O padrão é 443, então especifique a porta personalizada sempre que o endpoint estiver escutando em outro lugar, caso contrário, o host não corresponderá e nenhum certificado será enviado.

Certificados não são editáveis após serem adicionados. Não há ação de edição. Para girar um certificado renovado ou corrigir um erro de digitação no host, remova o existente com o ícone de exclusão e adicione-o novamente. Incorpore isso em seu manual de rotação de certificados para que ninguém procure um botão de edição que não existe.

Um certificado por domínio. Não registre dois certificados de cliente para o mesmo domínio. Cada vinculação é específica do domínio, e uma duplicação cria ambiguidade sobre qual o Apidog deve apresentar. Mantenha um por host.

Mantenha os certificados e a Autorização separados em sua mente. Esta é a maior fonte de confusão. O mTLS reside na aba Certificados. Chaves de API, tokens de portador, OAuth e autenticação Básica residem na aba Autorização de uma requisição ou pasta, e as requisições herdam a autorização de sua pasta pai. A Autorização se aplica em três níveis: requisições individuais, todas as requisições em uma pasta e todas as requisições em uma coleção. Se um parceiro precisar de um certificado de cliente e OAuth, você configura o certificado em Certificados e o token em Autorização. Eles não se sobrepõem. Para uma visão mais aprofundada sobre como configurar a autenticação baseada em token, o guia de autenticação de gateway de API cobre o lado da requisição, e se você estiver lidando com uma pilha pesada em Windows, configurar a autenticação Kerberos no Apidog é um tutorial irmão que vale a pena marcar.

Apenas HTTPS, sempre. O Apidog não anexará um certificado de cliente a uma requisição HTTP simples. Se o seu alvo de teste for http://, o certificado nunca é enviado e a lógica do handshake nunca é executada. O endpoint deve ser HTTPS para que qualquer um desses conceitos se aplique.

Automatize o fluxo de trabalho com o CLI do Apidog

Uma vez que suas requisições mTLS passem manualmente, integre-as em cenários de teste salvos e execute-as sem interface gráfica com o CLI do Apidog. Instale-o e autentique-se:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Em seguida, execute um cenário salvo contra um ambiente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

O comando apidog run suporta a configuração de certificado de cliente diretamente, então o mTLS sobrevive à transição da GUI para o pipeline. Para um único certificado, passe --ssl-client-cert (o certificado PEM), --ssl-client-key (a chave privada) e --ssl-client-passphrase se a chave tiver uma senha. Aponte --ssl-extra-ca-certs para CAs confiáveis adicionais, ou use --ssl-client-cert-list com um arquivo de configuração quando você combinar certificados com hosts por padrão de URL. Os reportadores são definidos com -r (experimente -r html,cli). Conecte esse comando a um job e sua API protegida por certificado será testada em cada push. O guia CLI do Apidog em CI/CD aborda como executá-lo dentro de um pipeline.

Perguntas frequentes

Preciso de um certificado de cliente e um certificado CA, ou apenas um?

Depende do endpoint. Um certificado de cliente prova sua identidade, então você precisará dele sempre que o servidor exigir TLS mútuo. Um certificado CA é necessário apenas quando o próprio certificado do servidor é assinado por uma autoridade em que sua máquina ainda não confia, como uma CA raiz interna. Uma API de parceiro pública em uma CA pública confiável precisa apenas do certificado de cliente; um serviço mTLS interno em uma raiz privada geralmente precisa de ambos.

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

Quase sempre é uma incompatibilidade de host ou um alvo HTTP simples. Verifique se o campo Host contém o domínio exato sem o prefixo https://, se a porta corresponde (padrão 443, então defina uma porta personalizada se o endpoint escutar em outro lugar) e se a URL da requisição é HTTPS. O Apidog nunca anexa um certificado a uma requisição HTTP.

Onde as chaves de API e os tokens de portador vão se não estão nos Certificados?

Na aba Autorização da requisição ou pasta, que é separada da configuração do certificado. Os certificados lidam com a identidade da camada TLS; a Autorização lida com a Chave de API, Token de Portador, OAuth e autenticação Básica na camada de requisição. Você pode encontrar a descrição completa dos tipos de autenticação no guia de esquemas de segurança, e você pode definir a autenticação uma vez no nível da pasta ou coleção para que cada requisição a herde.

Um único certificado pode cobrir vários subdomínios?

Sim. O campo host suporta correspondência de padrões. Insira *.example.com e o mesmo certificado de cliente se aplica a todos os subdomínios de example.com. Essa é a maneira limpa de reutilizar um certificado com escopo curinga que um parceiro emitiu para vários de seus subdomínios de API.

Como atualizo um certificado depois de adicionado?

Os certificados não são editáveis no local. Remova o existente com o ícone de exclusão e adicione a versão corrigida ou renovada. Tenha isso em mente para a rotação de certificados, e enquanto você organiza as configurações de teste, definir parâmetros globais no Apidog combina bem para manter os valores do ambiente organizados em todas as requisições.

Conclusão

Testar uma API protegida por mTLS se resume a três ações no Apidog: vincular um certificado de cliente ao host correto, anexar um certificado CA se o servidor usar uma raiz privada e deixar a correspondência de host assinar automaticamente cada requisição HTTPS. Mantenha os certificados e a Autorização em seus próprios lugares e o handshake deixa de ser um mistério.

Baixe o Apidog para acompanhar, adicione o certificado do seu parceiro e envie a primeira requisição autenticada. Experimente gratuitamente, sem necessidade de cartão de crédito.