Skip to main content

Autenticação

A Banking API usa autenticação EdDSA Proof-of-Possession (PoP). Este método criptográfico garante que as requisições sejam assinadas pelo proprietário legítimo da chave privada da conta de serviço e previne ataques de replay.

Visão Geral

Diferente da autenticação tradicional por API key ou OAuth, a autenticação PoP requer que você assine criptograficamente cada requisição. Isso fornece:
  • Não-repúdio - Requisições podem ser comprovadas como originárias da sua conta de serviço
  • Proteção contra replay - Timestamps previnem reutilização de requisições capturadas

Pré-requisitos

Antes de fazer requisições à API, você precisa:
  1. Conta de Serviço - Criada no seu painel Conta Digital
  2. Par de Chaves Ed25519 - Gere um par de chaves pública/privada
  3. Chave Pública Registrada - Faça upload da sua chave pública na conta de serviço

Headers Obrigatórios

Toda requisição autenticada deve incluir estes 4 headers:

Processo de Assinatura

A assinatura é criada assinando um formato de mensagem específico com sua chave privada Ed25519.

Passo 1: Construir a Mensagem

Concatene os seguintes valores separados por dois-pontos (:):

Passo 2: Assinar a Mensagem

Assine a mensagem usando sua chave privada Ed25519 e codifique a assinatura em base64.

Passo 3: Definir os Headers

Inclua a assinatura e todos os headers obrigatórios na sua requisição.

Exemplos de Código

Node.js

Python

cURL (com assinatura pré-computada)

Validação de Timestamp

O timestamp X-PoP-Challenge deve estar dentro de 5 minutos do horário atual do servidor. Isso previne ataques de replay enquanto permite uma margem razoável para diferença de relógios.
Certifique-se de que o relógio do seu sistema está sincronizado usando NTP. Requisições com timestamps fora da janela de 5 minutos serão rejeitadas com erro 401 Unauthorized.

Solução de Problemas

Erros Comuns

Causa: A assinatura não corresponde ao valor esperado.Soluções:
  • Verifique se está assinando o formato exato da mensagem: {uri}:{method}:{body}:{timestamp}
  • Certifique-se de que a URI inclui o caminho completo e a query string
  • Verifique se a string do body corresponde exatamente ao que está enviando
  • Confirme que sua chave privada corresponde à chave pública registrada na conta de serviço
Causa: O timestamp X-PoP-Challenge está mais de 5 minutos diferente do horário do servidor.Soluções:
  • Sincronize o relógio do seu sistema usando NTP
  • Gere o timestamp imediatamente antes de fazer a requisição
  • Certifique-se de usar milissegundos, não segundos
Causa: O x-access-id não corresponde a nenhuma conta de serviço ativa.Soluções:
  • Verifique se o UUID da conta de serviço está correto
  • Certifique-se de que a conta de serviço está ativa e não desabilitada
  • Verifique se há erros de digitação ou espaços extras

Dicas de Depuração

  1. Registre a mensagem antes de assinar - Imprima a string exata sendo assinada para verificar o formato
  2. Teste com uma assinatura conhecida - Use vetores de teste para verificar sua implementação de assinatura
  3. Verifique os headers de resposta - Respostas de erro podem incluir informações adicionais de depuração
  4. Verifique o formato da chave - Chaves privadas Ed25519 devem ter 32 bytes (64 caracteres hexadecimais)

Melhores Práticas de Segurança

Proteja Sua Chave Privada

Nunca exponha sua chave privada em código client-side, logs ou controle de versão. Use variáveis de ambiente ou gerenciamento seguro de secrets.

Rotacione Chaves Regularmente

Gere novos pares de chaves periodicamente e atualize sua conta de serviço. Revogue chaves antigas após a rotação.

Monitore o Uso da API

Revise regularmente seus logs de acesso à API para padrões inesperados ou tentativas não autorizadas.