Autenticação

​

Visão Geral

​

Obtendo Sua Chave de API

1. Faça login na sua conta VoxFi em https://voxfi.com.br/profile
2. Navegue até Perfil → Segurança
3. Clique em Criar API Key ou Criar Nova Chave de API
4. Configure as opções da sua chave de API:
   • Nome (obrigatório): Dê um nome descritivo para sua chave (ex: “Aplicativo mobile”, “Servidor produção”)
   • Data de expiração (obrigatório): Defina quando a chave de API deve expirar
   • Permissões (opcional): Selecione permissões específicas para a chave. Se nenhuma for selecionada, todas as permissões serão concedidas:
     • Ler ordens
     • Criar ordens
     • Cancelar ordens
     • Ler posições
     • Ler carteira
   • IPs permitidos (opcional): Especifique os endereços IP permitidos para usar esta chave (separados por vírgula). Se vazio, todos os IPs serão permitidos
5. Clique em Criar para gerar sua chave de API
6. Copie sua chave de API imediatamente - ela será gerada automaticamente e exibida apenas uma vez
7. Armazene-a com segurança usando as melhores práticas descritas abaixo

​

Usando Sua Chave de API

X-Api-Key: sua-chave-de-api-aqui

​

Exemplo de Requisição

curl -X GET "https://data-api.voxfi.com.br/v1/data/events" \
  -H "X-Api-Key: sua-chave-de-api-aqui"

​

Boas Práticas de Segurança

​

✅ Faça

// arquivo .env (nunca commite isso!)
VOXFI_API_KEY=sua-chave-de-api-aqui

// No seu código
const apiKey = process.env.VOXFI_API_KEY;

const response = await fetch('https://data-api.voxfi.com.br/v1/data/events', {
  headers: {
    'X-Api-Key': apiKey
  }
});

• AWS Secrets Manager / AWS Parameter Store
• Google Cloud Secret Manager
• Azure Key Vault
• HashiCorp Vault
• 1Password Secrets Automation
• GitHub Secrets (para CI/CD)

• Gere novas chaves de API periodicamente
• Revogue chaves antigas que não estão mais em uso
• Use chaves diferentes para ambientes diferentes (desenvolvimento, staging, produção)

• Nome: Use nomes descritivos para identificar a finalidade de cada chave
• Whitelist de IP: Restrinja o uso da chave de API a endereços IP específicos (separados por vírgula)
• Permissões: Selecione apenas as permissões que sua aplicação precisa (ler ordens, criar ordens, cancelar ordens, ler posições, ler carteira)
• Expiração: Defina datas de expiração para acesso temporário

• Revise regularmente os logs de uso das chaves de API
• Configure alertas para atividade incomum
• Monitore tentativas de acesso não autorizado

​

❌ Não Faça

# ❌ RUIM - Nunca faça isso!
const API_KEY = "voxfi_abc123xyz789";

# ✅ BOM - Use variáveis de ambiente
const API_KEY = process.env.VOXFI_API_KEY;

# .gitignore
.env
.env.local
.env.*.local
*.key
secrets/
config/secrets.json

• Nunca publique chaves de API em fóruns, salas de chat ou repositórios públicos
• Não inclua chaves em screenshots ou exemplos de documentação
• Evite enviar chaves por email ou mensagens não criptografadas

• JavaScript do navegador
• Código de aplicativos móveis que pode ser descompilado
• Repositórios públicos
• Arquivos de configuração do lado do cliente

• Use chaves separadas para aplicações diferentes
• Use chaves separadas para ambientes diferentes
• Rotacione chaves quando membros da equipe saírem

​

Armazenamento por Ambiente

​

Desenvolvimento

# .env.local (não commitado)
VOXFI_API_KEY=sua-chave-dev

​

Produção

import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";

const client = new SecretsManagerClient({ region: "us-east-1" });
const response = await client.send(
  new GetSecretValueCommand({ SecretId: "voxfi/api-key" })
);
const apiKey = JSON.parse(response.SecretString).apiKey;

​

Pipelines CI/CD

# .github/workflows/api.yml
env:
  VOXFI_API_KEY: ${{ secrets.VOXFI_API_KEY }}

# .gitlab-ci.yml
variables:
  VOXFI_API_KEY: $VOXFI_API_KEY  # Configure nas variáveis CI/CD

​

Rotação de Chaves

1. Crie uma nova chave de API em Perfil → Segurança com as mesmas ou configurações atualizadas
2. Copie a nova chave de API gerada automaticamente
3. Atualize todas as aplicações usando a chave antiga
4. Revogue a chave de API antiga
5. Verifique se todas as aplicações estão funcionando com a nova chave
6. Monitore tentativas de acesso não autorizado

​

Whitelist de IP

1. Vá para Perfil → Segurança
2. Ao criar sua chave de API, insira os endereços IP permitidos no campo “IPs permitidos” (separados por vírgula, ex: 192.168.1.1, 10.0.0.1)
3. Apenas requisições de IPs na whitelist serão aceitas
4. Se deixado vazio, todos os IPs serão permitidos
5. Para atualizar IPs de uma chave existente, você precisará criar uma nova chave com IPs atualizados e revogar a antiga

​

Solução de Problemas

​

Erro “unauthorized”

1. Verifique se sua chave de API está correta
2. Confirme que o cabeçalho X-Api-Key está incluído na sua requisição
3. Certifique-se de que sua chave de API não expirou
4. Verifique se sua chave de API está habilitada
5. Verifique se a whitelist de IP não está bloqueando sua requisição

​

Erro “ip not allowed”

1. Verifique seu endereço IP atual
2. Confirme se seu IP está na whitelist da sua chave de API
3. Atualize a whitelist em Perfil → Segurança se necessário

​

Recursos Adicionais

• Guia de Início Rápido - Comece com sua primeira requisição à API
• Referência da API - Documentação completa dos endpoints
• Tratamento de Erros - Entenda as respostas de erro da API