Autenticacao
A Banking API usa autenticacao EdDSA Proof-of-Possession (PoP). Este metodo criptografico garante que as requisicoes sejam assinadas pelo proprietario legitimo da chave privada da conta de servico e previne ataques de replay.Visao Geral
Diferente da autenticacao tradicional por API key ou OAuth, a autenticacao PoP requer que voce assine criptograficamente cada requisicao. Isso fornece:- Nao-repudio - Requisicoes podem ser comprovadas como originarias da sua conta de servico
- Protecao contra replay - Timestamps previnem reutilizacao de requisicoes capturadas
- Vinculacao de IP - Requisicoes sao validadas contra sua lista de IPs permitidos
Pre-requisitos
Antes de fazer requisicoes a API, voce precisa:- Conta de Servico - Criada no seu painel Conta Digital
- Par de Chaves Ed25519 - Gere um par de chaves publica/privada
- Chave Publica Registrada - Faca upload da sua chave publica na conta de servico
- Lista de IPs Permitidos - Configure os enderecos IP permitidos para sua conta de servico
Headers Obrigatorios
Toda requisicao autenticada deve incluir estes 5 headers:| Header | Descricao | Exemplo |
|---|---|---|
x-access-id | UUID da sua conta de servico | 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 autenticacao | service-account |
true-client-ip | Endereco IP do seu cliente | 203.0.113.50 |
Processo de Assinatura
A assinatura e criada assinando um formato de mensagem especifico com sua chave privada Ed25519.Passo 1: Construir a Mensagem
Concatene os seguintes valores separados por dois-pontos (:):
| Componente | Descricao |
|---|---|
uri | Caminho completo da requisicao incluindo query string (ex: /v1/account?include=balance) |
method | Metodo HTTP em maiusculas (ex: GET, POST) |
body | Corpo da requisicao como string, ou string vazia para requisicoes 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 obrigatorios na sua requisicao.Exemplos de Codigo
Node.js
Python
cURL (com assinatura pre-computada)
Validacao de Timestamp
O timestampX-PoP-Challenge deve estar dentro de 5 minutos do horario atual do servidor. Isso previne ataques de replay enquanto permite uma margem razoavel para diferenca de relogios.
Lista de IPs Permitidos
O valor do headertrue-client-ip deve corresponder a um dos enderecos IP configurados na lista de permitidos da sua conta de servico. Isso fornece uma camada adicional de seguranca.
Para configurar sua lista de IPs permitidos:
- Acesse seu painel Conta Digital
- Navegue ate Configuracoes > Contas de Servico
- Edite sua conta de servico
- Adicione os enderecos IP permitidos (IPv4 ou IPv6)
Solucao de Problemas
Erros Comuns
401 - Assinatura invalida
401 - Assinatura invalida
Causa: A assinatura nao corresponde ao valor esperado.Solucoes:
- Verifique se esta 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 esta enviando
- Confirme que sua chave privada corresponde a chave publica registrada na conta de servico
401 - Timestamp expirado
401 - Timestamp expirado
Causa: O timestamp
X-PoP-Challenge esta mais de 5 minutos diferente do horario do servidor.Solucoes:- Sincronize o relogio do seu sistema usando NTP
- Gere o timestamp imediatamente antes de fazer a requisicao
- Certifique-se de usar milissegundos, nao segundos
403 - IP nao permitido
403 - IP nao permitido
Causa: O
true-client-ip nao corresponde a lista de IPs permitidos da sua conta de servico.Solucoes:- Verifique seu endereco IP publico atual
- Atualize a lista de IPs permitidos da sua conta de servico no painel
- Se estiver atras de um proxy/NAT, use o endereco IP externo
401 - Access ID invalido
401 - Access ID invalido
Causa: O
x-access-id nao corresponde a nenhuma conta de servico ativa.Solucoes:- Verifique se o UUID da conta de servico esta correto
- Certifique-se de que a conta de servico esta ativa e nao desabilitada
- Verifique se ha erros de digitacao ou espacos extras
Dicas de Depuracao
- 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 implementacao de assinatura
- Verifique os headers de resposta - Respostas de erro podem incluir informacoes adicionais de depuracao
- Verifique o formato da chave - Chaves privadas Ed25519 devem ter 32 bytes (64 caracteres hexadecimais)
Melhores Praticas de Seguranca
Proteja Sua Chave Privada
Nunca exponha sua chave privada em codigo client-side, logs ou controle de versao. Use variaveis de ambiente ou gerenciamento seguro de secrets.
Rotacione Chaves Regularmente
Gere novos pares de chaves periodicamente e atualize sua conta de servico. Revogue chaves antigas apos a rotacao.
Minimize a Lista de IPs
Permita apenas IPs que genuinamente precisam de acesso a API. Use IPs especificos ao inves de ranges CIDR amplos.
Monitore o Uso da API
Revise regularmente seus logs de acesso a API para padroes inesperados ou tentativas nao autorizadas.
