Autenticação

A DEX API utiliza o fluxo de autenticação OAuth 2.0 Client Credentials Grant, que é o padrão de mercado mais seguro para comunicação de máquina para máquina (M2M) — ou seja, comunicação entre o seu Backend e a nossa plataforma.

Neste fluxo, não há interação de um usuário humano. Seu sistema autentica-se diretamente contra os servidores da EtherBank utilizando chaves fornecidas no seu painel de parceiro.

1. Suas Credenciais

Ao ser aprovado como parceiro B2B (BaaS), você receberá acesso ao Painel do Participante. Nele, você poderá gerar:

• Client ID: Identificador público da sua aplicação.

• Client Secret: Chave secreta da sua aplicação. Nunca compartilhe ou exponha essa chave no lado do cliente (Frontend ou Apps Móveis).

⚠️ Aviso de Segurança: O Client Secret é gerado apenas uma vez. Se você perdê-lo, precisará revogar a chave atual e gerar uma nova.

2. Gerando o Token de Acesso (JWT)

Para interagir com qualquer endpoint protegido da nossa API, você primeiro precisa trocar seu Client ID e Client Secret por um Access Token temporário.

Endpoint de Autenticação

POST /v1/auth/api-key

Formato da Requisição (JSON):

{
  "clientId": "seu_client_id_aqui",
  "clientSecret": "seu_client_secret_super_secreto_aqui"
}

Exemplo de Resposta de Sucesso:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

O accessToken recebido é um JSON Web Token (JWT) e possui validade. O campo expiresIn indica o tempo (em segundos) até que o token expire (ex: 3600 segundos = 1 hora).

3. Realizando Chamadas Autenticadas

Com o token em mãos, você deverá enviá-álo em todas as requisições subsequentes usando o Header HTTP Authorization, com o prefixo Bearer.

Exemplo de uso via cURL:

curl -X GET "https://api.dexkey.finance/v1/users/wallets-status" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

4. Melhores Práticas de Gestão de Tokens

Para extrair o melhor desempenho e não esbarrar em limites de rate-limit (Too Many Requests), recomendamos fortemente:

1. Faça Cache do Token: Não solicite um novo token a cada chamada à API. Armazene o token no seu servidor (ex: no Redis ou memória) e reutilize-o para todas as requisições.

2. Atualização Antecipada: Verifique a expiração do token localmente. Solicite um novo token (fazendo um novo POST para /auth/api-key) cerca de 1 a 2 minutos antes do token atual expirar no cache.

3. Tratamento do Erro 401: Se a API retornar um HTTP 401 Unauthorized mesmo enviando um token, isso significa que seu token expirou ou foi invalidado. A sua aplicação deve estar preparada para interceptar esse erro, gerar um novo token e re-tentar a requisição original de forma invisível.