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:- Conta de Serviço - Criada no seu painel Conta Digital
- Par de Chaves Ed25519 - Gere um par de chaves pública/privada
- 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:| Header | Descrição | Exemplo |
|---|---|---|
x-access-id | UUID da sua conta de serviço | 550e8400-e29b-41d4-a716-446655440000 |
X-PoP-Signature | Assinatura EdDSA (base64) | MEUCIQDx... |
X-PoP-Challenge | Timestamp Unix em milissegundos | 1705423200000 |
X-PoP-Format | Identificador do tipo de autenticação | service-account |
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 (:):
| Componente | Descrição |
|---|---|
uri | Caminho completo da requisição incluindo query string (ex: /v1/account?include=balance) |
method | Método HTTP em maiúsculas (ex: GET, POST) |
body | Corpo da requisição como string, ou string vazia para requisições GET |
timestamp | Mesmo valor do header X-PoP-Challenge |
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 timestampX-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.
Solução de Problemas
Erros Comuns
401 - Assinatura inválida
401 - Assinatura inválida
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
401 - Timestamp expirado
401 - Timestamp expirado
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
401 - Access ID inválido
401 - Access ID inválido
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
- Registre a mensagem antes de assinar - Imprima a string exata sendo assinada para verificar o formato
- Teste com uma assinatura conhecida - Use vetores de teste para verificar sua implementação de assinatura
- Verifique os headers de resposta - Respostas de erro podem incluir informações adicionais de depuração
- 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.
