Documentação da API

Padrões Avançados de Autenticação — OAuth 2.0, JWT, Rotação de Chaves

Domine mecanismos sofisticados de autenticação para integrar a Smart Money API em ambientes empresariais. Aprenda fluxos OAuth 2.0, padrões de tokens JWT, rotação segura de chaves e implementação de autenticação multi-fator.

Publicado em 21 de março de 2026 • 18 min de leitura • Avançado

Visão Geral de Autenticação

A Smart Money API suporta múltiplos métodos de autenticação projetados para acomodar diferentes arquiteturas de aplicação, requisitos de segurança e políticas organizacionais. Compreender esses padrões garante que sua integração seja segura e performática.

A autenticação na Smart Money API opera em três camadas principais:

  • Chaves de API — Autenticação simples por token bearer para desenvolvimento e integrações diretas
  • Tokens JWT — Tokens assinados criptograficamente e sem estado para sistemas distribuídos e microsserviços
  • OAuth 2.0 — Framework de autorização delegada para integrações de terceiros e aplicações SaaS

Princípio de Segurança: Nunca exponha credenciais de autenticação em código do lado do cliente, logs, controle de versão ou mensagens de erro. Implemente rotação de credenciais em um cronograma e imediatamente em caso de comprometimento.

Cada método tem vantagens distintas. Chaves de API funcionam melhor para comunicação backend-to-backend onde o armazenamento de credenciais é controlado. Tokens JWT se destacam em arquiteturas distribuídas onde não há estado compartilhado. OAuth 2.0 fornece acesso delegado pelo usuário para aplicativos de terceiros.

Autenticação de Chave de API

As chaves de API são o mecanismo de autenticação mais simples—elas são strings aleatórias geradas para sua conta que identificam sua aplicação para a Smart Money API. Cada solicitação deve incluir sua chave de API, seja como um cabeçalho ou parâmetro de consulta.

Chave de API Baseada em Cabeçalho

A abordagem recomendada é passar sua chave de API no cabeçalho Authorization usando o esquema Bearer:

Exemplo de curl
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"

Chave de API como Parâmetro de Consulta

Para conexões WebSocket ou quando os cabeçalhos não podem ser modificados, passe a chave de API como um parâmetro de consulta:

Conexão WebSocket
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Estabelece um fluxo WebSocket autenticado

Características da Chave de API

Propriedade Descrição
Formato String hexadecimal de 128 caracteres prefixada com sk_test_ ou sk_live_
Escopo Herdar todas as permissões da conta que a criou
Expiração Nunca expira automaticamente; deve ser rotacionada manualmente
Rotação Gere uma nova chave, migre o tráfego e então desative a chave antiga
Limites de Taxa Compartilhados entre todas as solicitações que usam a mesma chave

Práticas de Segurança para Chaves de API

  • Variáveis de Ambiente — Armazene as chaves em arquivos .env (não commitados no controle de versão) e carregue-as em tempo de execução
  • Sistemas de Cofre — Use o HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault em produção
  • Chaves Separadas — Mantenha chaves de teste e produção separadas; rotacione as chaves de teste com frequência
  • Escopo Mínimo — Crie chaves separadas para diferentes integrações sempre que possível
  • Registro de Auditoria — Registre todos os eventos de criação e uso de chaves de API
Obtenha sua chave de API em 30 segundos

Pronto para construir? Pegue uma chave de API gratuita (200 chamadas/dia, sem cartão) e comece a puxar dados ao vivo de baleias, financiamento e on-chain.

Obtenha sua chave de API →

Padrão de Token Bearer

Os tokens bearer estendem o conceito simples de chave de API ao adicionar contexto, expiração e mecanismos de atualização. Eles são ideais para aplicativos que precisam de gerenciamento programático de credenciais.

Obtenção de Tokens Bearer

Troque sua chave de API e segredo por um token bearer válido por 24 horas:

GET /auth/token
curl -X POST "https://api.smartmoneyapi.com/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_1234567890",
"api_secret": "secret_abc123xyz"
}'

Formato de Resposta do Token

O endpoint retorna um token bearer com metadados:

Resposta
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}

Usando Tokens Bearer

Inclua o token no cabeçalho Authorization para todas as solicitações subsequentes:

Solicitação Autenticada
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Fluxo de Atualização de Token

Quando um token estiver próximo da expiração, use o token de atualização para obter um novo sem exigir seu segredo de API:

POST /auth/refresh
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'

Implementação do OAuth 2.0

O OAuth 2.0 permite que os usuários concedam acesso às suas contas da Smart Money API para aplicativos sem compartilhar credenciais. Isso é essencial para plataformas SaaS, integrações de terceiros e aplicativos multi-inquilinos.

Fluxo de Código de Autorização do OAuth 2.0

O fluxo padrão para aplicativos web:

  1. Usuário Inicia o Login — O usuário clica em "Conectar com Smart Money API"
  2. Redirecionamento para o Servidor de Autorização — Seu aplicativo redireciona o usuário para o endpoint de autorização da Smart Money
  3. Usuário Concede Permissão — O usuário revisa os escopos solicitados e concede acesso
  4. Código de Autorização Retornado — O usuário é redirecionado de volta com o código de autorização
  5. Troca de Código por Token — O backend troca o código por um token de acesso (o código nunca é exposto ao frontend)
  6. Armazenamento do Token — Armazene o token de atualização com segurança; use o token de acesso para chamadas de API

Passo 1: Redirecionar o Usuário para o Endpoint de Autorização

Redirecionamento no Frontend
// URL para redirecionar o usuário
const authUrl = new URL('https://api.smartmoneyapi.com/oauth/authorize');
authUrl.searchParams.append('client_id', 'your_client_id');
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'whales derivatives onchain');
authUrl.searchParams.append('state', generateRandomState());
window.location.href = authUrl.toString();

Passo 2: Lidar com o Callback e Trocar o Código

Troca de Código no Backend
// O backend lida com a rota /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Verificar o parâmetro state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// Trocar código por token
const tokenResponse = await fetch('https://api.smartmoneyapi.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code: code,
client_id: process.env.OAUTH_CLIENT_ID,
client_secret: process.env.OAUTH_CLIENT_SECRET,
redirect_uri: 'https://yourapp.com/callback'
})
});
const tokens = await tokenResponse.json();
// Armazenar tokens com segurança

Escopos do OAuth

Solicite apenas os escopos que sua aplicação precisa. O Smart Money API define estes escopos:

Escopo Descrição
whales Acesso a métricas de rastreamento e acumulação de carteiras de baleias
derivatives Acesso a dados de futuros, perpétuos e taxas de funding
onchain Acesso a fluxos de transações e análises on-chain
alerts Criar e gerenciar alertas via webhook
offline Acesso a tokens de atualização para obter novos tokens offline

Gerenciamento de Tokens JWT

JWT (JSON Web Tokens) fornece autenticação sem estado—o servidor não precisa armazenar dados de sessão. O Smart Money API usa RS256 (Assinatura RSA com SHA-256) para assinar tokens, permitindo verificação sem contatar a API.

Estrutura do JWT

Tokens JWT consistem em três partes separadas por pontos:

Formato JWT
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// CABEÇALHO.PAYLOAD.ASSINATURA

Cabeçalho JWT

O cabeçalho identifica o algoritmo e o tipo de token:

Cabeçalho Decodificado
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}

Claims do Payload JWT

O payload contém claims (declarações sobre o usuário/aplicativo):

Payload Decodificado
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}

Verificando Assinaturas JWT

Baixe a chave pública do Smart Money e verifique os tokens antes de aceitá-los:

Verificação em Node.js
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Obter chave pública do Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Verificar token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Token válido, use as claims decodificadas
} catch (err) {
// Token inválido ou expirado
}

Estratégia de Rotação de Chaves

A rotação regular de chaves é crítica para manter a segurança. Mesmo com práticas de segurança perfeitas, assuma que as chaves podem ser comprometidas e implemente rotação sistemática.

Frequência de Rotação

O Smart Money recomenda diferentes cronogramas de rotação com base no tipo e uso da chave:

Tipo de Chave Rotação Recomendada Rotação Mínima
Chaves de API de Teste Mensal Trimestral
Chaves de API de Produção Trimestral Anual
Tokens de Atualização OAuth Automática (após 90 dias) Manual (após 180 dias)
Chaves de Conta de Serviço Semestral Anual

Processo de Rotação sem Tempo de Inatividade

Gire as chaves sem interromper o serviço:

  1. Gerar Nova Chave — Crie uma nova chave de API pelo painel ou API
  2. Implantar Nova Chave — Atualize os segredos da aplicação em staging, teste minuciosamente
  3. Lançamento Gradual — Implante em 10% dos servidores, monitore erros
  4. Lançamento Completo — Implementar nos servidores restantes
  5. Verificar Tráfego — Confirmar que todas as solicitações usam a nova chave
  6. Desativar Chave Antiga — Marcar a chave antiga como inativa, mas não excluir imediatamente
  7. Excluir Chave Antiga — Após 48 horas sem erros, excluir permanentemente

Rotação de Chave de Emergência

Se você suspeitar que uma chave foi comprometida:

Rotação de Emergência
// Ação imediata: Desativar a chave comprometida
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Gerar uma chave substituta imediatamente
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Chave de Substituição de Emergência"
}'

Rotação Automatizada no Kubernetes

Use Secrets e operadores do Kubernetes para rotação automática:

CronJob para Rotação de Chave
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Semanalmente no domingo
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest

Autenticação Multi-Fator (MFA)

Para contas que acessam dados de produção, o MFA fornece uma camada adicional de segurança ao exigir um segundo fator além das credenciais.

Métodos de MFA Suportados

  • TOTP (Senha de Uso Único Baseada em Tempo) — Aplicativos como Google Authenticator, Authy
  • WebAuthn/FIDO2 — Chaves de segurança de hardware, biometria
  • Códigos de Uso Único por SMS — Menos seguro, mas universalmente suportado
  • Confirmação por E-mail — Códigos de confirmação enviados para o e-mail registrado

Habilitando TOTP para Acesso à Conta

Habilitar MFA
// Passo 1: Solicitar configuração do MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// A resposta inclui a URL do QR code
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}

MFA Durante Operações de API

Algumas operações podem exigir confirmação de MFA mesmo após a autenticação:

Desafio de MFA
// Tentando uma operação sensível (rotação de chave)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Resposta: MFA necessário
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Tentar novamente com o código TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"

Melhores Práticas de Segurança

A autenticação é tão forte quanto sua implementação. Siga estas práticas para manter a segurança:

Gerenciamento de Segredos

  • Nunca comprometa segredos no controle de versão — Use arquivos .env com .gitignore
  • Use variáveis de ambiente — Carregue de sistemas seguros de gerenciamento de segredos
  • Escaneie repositórios — Use ferramentas como TruffleHog, detect-secrets para encontrar chaves expostas
  • Audite logs de acesso — Monitore quem acessou os segredos e quando

Segurança de Transporte

  • Sempre use HTTPS — Nunca envie credenciais por conexões não criptografadas
  • Verifique certificados SSL — Não desative a validação de certificados em produção
  • Use fixação de certificado — Para aplicativos móveis, evite ataques MITM
  • Impulsione TLS 1.2+ — Desative protocolos mais antigos

Manuseio de Credenciais

  • Hash de segredos — Armazene hashes bcrypt ou Argon2, nunca em texto claro
  • Minimize o tempo de vida — Mantenha credenciais na memória apenas pelo tempo necessário
  • Limpe dados sensíveis — Sobrescreva explicitamente as credenciais após o uso
  • Use bibliotecas seguras — Não implemente criptografia você mesmo

Registro e Monitoramento

  • Nunca registre credenciais — Reduza chaves em logs, use máscara de log
  • Registre eventos de autenticação — Acompanhe tentativas de login bem-sucedidas e falhas
  • Monitore anomalias — Alerte sobre padrões de acesso incomuns
  • Audite o uso de chaves — Acompanhe quais chaves acessaram quais dados

Padrões de Autenticação Empresarial

Grandes organizações frequentemente exigem controles de segurança adicionais e capacidades de conformidade.

Integração SAML 2.0

Para clientes empresariais, o Smart Money API suporta integração SAML 2.0 com o provedor de identidade da sua organização (Okta, Azure AD, etc.):

  • Single Sign-On (SSO) — Os usuários se autenticam através do IdP corporativo
  • Provisionamento automático — Crie/desative contas com base na associação ao grupo
  • Imposição — Exija SAML para todo acesso de usuário

Lista de IPs Permitidos

Restringir o acesso à API a endereços IP ou intervalos CIDR específicos:

Gerenciamento de Lista Branca de IP
// Adicionar IP à lista branca
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Servidores de produção"
}'

Registro de Auditoria e Conformidade

Planos empresariais incluem registros de auditoria abrangentes para conformidade:

Evento Dados Registrados
Autenticação Usuário, carimbo de data/hora, sucesso/falha, IP, status MFA
Operações de Chave ID da chave, ação, iniciador, carimbo de data/hora
Alterações na Conta O que mudou, quem alterou, carimbo de data/hora, valores antes/depois
Acesso a Dados Usuário, endpoint, escopos, carimbo de data/hora, contagem de registros

Solução de Problemas de Autenticação

Erro de Chave de API Inválida

Problema: Recebendo "401 Não Autorizado - Chave de API Inválida"

Soluções:

  • Verifique o formato da chave (deve começar com sk_test_ ou sk_live_)
  • Verifique espaços em branco no início/fim da chave
  • Confirme se a chave não foi desativada ou substituída
  • Verifique se está usando o ambiente correto (chave de teste para teste, chave real para produção)
  • Verifique se as permissões da chave de API correspondem aos requisitos do endpoint

Erro de Token Expirado

Problema: Token Bearer expirado, solicitações falhando

Soluções:

  • Use o token de atualização para obter um novo token de acesso
  • Implemente a atualização automática do token 5 minutos antes da expiração
  • Armazene o token de atualização com segurança (não em localStorage para SPAs)
  • Trate respostas 401 tentando o fluxo de token de atualização

Erros de CORS/Preflight

Problema: Navegador bloqueando solicitações com erro CORS

Soluções:

  • Chamadas de API de navegadores devem vir de origens autorizadas
  • Adicione seu domínio via painel: Configurações → Origens CORS
  • Navegador envia solicitação OPTIONS preflight automaticamente
  • Para desenvolvimento, use localhost:3000 ou similar

Desafio MFA Não Concluído

Problema: Operações que exigem MFA falham mesmo com código correto

Soluções:

  • Certifique-se de que o relógio do servidor está sincronizado (TOTP depende do tempo)
  • O código é válido apenas por 30 segundos, gere um novo
  • Use códigos de backup se o aplicativo autenticador estiver indisponível
  • Recuperação de conta disponível via e-mail registrado

Implemente Autenticação Segura Hoje

A Smart Money API suporta autenticação de nível empresarial com OAuth 2.0, JWT, MFA e integração SAML. Proteja sua integração de API com as melhores práticas do setor.

Ver Planos Empresariais
Precisa de SAML, lista branca de IP ou suporte dedicado? Entre em contato com nossa equipe de vendas.

Recursos Relacionados

Guia de Autenticação →

Introdução à autenticação de API

Melhores Práticas de Segurança →

Guia abrangente de reforço de segurança

Referência de Códigos de Erro →

Solução de problemas de erros de autenticação
Comece de graça — 200 chamadas/dia, sem cartão

Obtenha dados de fluxo de baleias, financiamento, interesse aberto e on-chain em 3 exchanges a partir de uma API. Camada gratuita, sem cartão de crédito, atualize quando quiser.

Comece de graça →
Experimente o console de API ao vivo → (sem conta necessária)