Configurando o certificado mTLS

Passo a passo para conectar na API: gerar a credencial no portal, preparar o certificado e configurá-lo no Postman, no Insomnia e no Bruno. Cada etapa tem o print da tela, com os pontos de clique marcados. As telas do portal são do ambiente de homologação (sandbox).

Antes de começar

• client_id e client_secret da sua credencial (portal Finance → Desenvolvedor → Credenciais → Nova credencial) e o certificado emitido nesse mesmo passo.
• O certificado dessa credencial (.pfx + senha, ou o par .crt / .key).
• O host da sua API (informado pela ONZ, e varia por cliente).
• O IP público da máquina que vai chamar a API, cadastrado no campo IPs permitidos da credencial.

warning

O certificado é por credencial. O handshake mTLS só fecha com o certificado emitido junto daquela credencial, naquele ambiente. Certificado de outra credencial ou de outro ambiente resulta em tlsv1 alert decode error.

Gerar a credencial

No portal Finance, em Desenvolvedor → Credenciais, existem duas APIs, cada uma com credenciais próprias:

• API QRCodes: cobranças, QR Codes e recorrência.
• API de Contas: saldo, extrato e movimentação da conta.

O caminho é o mesmo nas duas. Muda a sub-aba e a lista de permissões.

API QRCodes

1. No menu lateral, abra Desenvolvedor → aba CREDENCIAIS. Confira que a sub-aba API QRCodes está selecionada.
2. Clique em Nova credencial.

3. No formulário, preencha a Descrição, ligue apenas as permissões do seu caso de uso e informe os IPs permitidos (o IP público de saída da sua aplicação).
4. Clique em Gerar.

5. A tela seguinte traz o client_id, o client_secret e o certificado (PFX + senha). É a única vez que eles aparecem. Baixe o PFX e guarde a senha antes de sair da tela.

API de Contas

1. Na mesma tela, clique na sub-aba API CONTAS.

2. Clique em Nova credencial.
3. Preencha a Descrição, ligue as permissões do seu caso de uso (a lista muda de uma API para a outra) e informe os IPs permitidos.

4. Clique em Gerar e baixe o PFX e a senha, como na API QRCodes.

A URL da API e a URL do token mudam de uma API para a outra. Use exatamente o host mostrado na tela da credencial que você gerou.

Preparar o certificado

Se você recebeu um .pfx

Os três clientes aceitam o .pfx diretamente. Se preferir usar .crt + .key, extraia:

openssl pkcs12 -in client.pfx -clcerts -nokeys -out client.crt
openssl pkcs12 -in client.pfx -nocerts -nodes -out client.key

Se você recebeu .crt + .key

Use os arquivos como estão. Confira que a chave corresponde ao certificado:

openssl x509 -in client.crt -noout -modulus | openssl md5
openssl rsa  -in client.key -noout -modulus | openssl md5

Os dois hashes devem ser iguais.

Configurar no cliente HTTP

O teste é o mesmo nos três: POST /oauth/token com grant_type=client_credentials no corpo deve responder 201. Se responder tlsv13 alert certificate required, o certificado não está sendo enviado. Se responder tlsv1 alert decode error, o certificado não é o daquela credencial.

Postman

Valide o certificado por fora antes de culpar o Postman

Rode este curl na mesma máquina que vai usar o Postman. Se ele responder 201, certificado e credencial estão corretos e o problema está na configuração da ferramenta:

curl -X POST https://SEU-HOST/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET' \
  --cert client.crt --key client.key -k

Esperado: HTTP 201.

{"access_token":"eyJhbGciOi…","expires_in":3600,"token_type":"Bearer"}

Abra as configurações

Na tela inicial, clique na engrenagem (canto superior direito) e escolha Settings.

Desligue a verificação de SSL

Na aba General, em SSL certificate verification: desligue o toggle.

Os certificados de servidor do ambiente são autoassinados. Com a verificação ligada, a requisição é abortada com self signed certificate. Alternativa: importar a CA do ambiente no sistema operacional e manter a verificação ligada.

Adicione o certificado do cliente

1. Ainda em Settings, abra a aba Certificates.
2. Em Client Certificates, clique em Add Certificate.

3. No formulário, preencha:
   • Host: somente o host, sem https:// e sem caminho, por exemplo api.seu-host.com.br;
   • Port: 443;
   • CRT file e KEY file: selecione client.crt e client.key, ou informe o PFX file e a Passphrase;
4. Clique em Add.

Armadilha: certificado invisível

O certificado no Postman é vinculado ao host. Se a URL da requisição apontar para outro host (ou vier com https:// no campo Host), o Postman não envia o certificado e a API responde tlsv13 alert certificate required.

Obtenha o token e chame a API

1. Nova requisição POST para https://SEU-HOST/oauth/token.

2. Aba Body → x-www-form-urlencoded:

   Chave	Valor
   grant_type	client_credentials
   client_id	seu client_id
   client_secret	seu client_secret

3. Sem header Authorization nesta chamada.

4. Send → resposta 201 com access_token e expires_in.

5. Nas chamadas seguintes, envie Authorization: Bearer <access_token>, no mesmo host, para o certificado continuar sendo enviado.

Armadilha: credenciais no lugar errado

client_id e client_secret vão no corpo, em x-www-form-urlencoded ou em JSON. Se forem enviados como Basic Auth, a resposta é 401 {"detail":"Credenciais inválidas APC-001"}.

O token é sempre solicitado em /oauth/token. O caminho /auth/token pertence à Banking API, que tem outro contrato.

Insomnia

1. Abra uma requisição e clique em Certificates na barra superior (ao lado de Cookies).
2. Em Manage Certificates você tem duas seções: CA Certificate (certificado do servidor) e Client Certificates (o seu certificado de cliente).
3. Em Client Certificates, clique em + Add client certificate.

4. No formulário, preencha:
   • Host: somente o host da API, sem https://, por exemplo api.seu-host.com.br;
   • Certificate: aponte o certificate file (.crt) e o key file (.key);
   • Passphrase: se a chave tiver senha;
   • ou alterne para PFX or PKCS12 e informe Add PFX or PKCS12 file + Passphrase.
5. Clique em + Add certificate e depois em Done.

Se o servidor usar certificado próprio, adicione a CA da ONZ em Add CA Certificate (um ou mais certificados em PEM, no mesmo arquivo).

Bruno

1. Abra Preferences (engrenagem no canto inferior esquerdo) e selecione Client Certificates.
2. Clique em Add Certificate.

3. No formulário, preencha:
   • Domain: o host da API. O prefixo de protocolo exibido acompanha a coleção ativa (grpcs:// em coleções gRPC, https:// em coleções HTTP). Digite apenas o host;
   • Type → Cert & Key: aponte Cert file (.crt) e Key file (.key) e informe a Passphrase;
   • ou Type → PFX: aponte o arquivo .pfx e informe a Passphrase.
4. Clique em Add.

No Bruno os certificados são gravados por caminho absoluto e enviados automaticamente em toda requisição feita ao domínio informado.

Problemas comuns

Mensagem	Causa provável	O que fazer
tlsv13 alert certificate required	O certificado não foi enviado	Confira o Host do certificado (só o host, igual ao da URL) e refaça a chamada
tlsv1 alert decode error	O certificado não é o da credencial (outra credencial ou outro ambiente)	Use o certificado emitido junto da credencial
401 Credenciais inválidas APC-001	client_id/client_secret ausentes, errados ou fora do corpo	Envie os dois no corpo, em x-www-form-urlencoded ou em JSON
403 Acesso Negado	IP de origem fora da allowlist da credencial	Cadastre o IP de saída da sua aplicação na credencial
self signed certificate / unable to verify the first certificate	Verificação SSL ligada com certificado de servidor autoassinado	Desligue a verificação SSL no cliente (ou importe a CA)
404 no endpoint	Host ou caminho incorreto	Confirme o host informado pela ONZ e o caminho /oauth/token

Boas práticas

1. Nunca versione .pfx, .key ou o client_secret em repositório. Use variáveis de ambiente do cliente HTTP ou um cofre de segredos.
2. O certificado e o segredo são por credencial: se vazar, revogue a credencial no portal e gere outra.
3. Renove o token antes de expirar (expires_in).
4. Planeje a rotação: é possível manter mais de uma credencial ativa durante a transição.
5. Não exponha o client_secret em aplicações de front-end. A integração é server-to-server.