> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxfi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Aprenda como autenticar e gerenciar suas chaves de API com segurança

## Visão Geral

Todas as requisições à API Pública VoxFi requerem autenticação usando uma chave de API. Sua chave de API identifica você para a API e concede acesso aos recursos da sua conta.

## Obtendo Sua Chave de API

Para criar uma chave de API:

1. Faça login na sua conta VoxFi em [https://staging.voxfi.com.br/profile](https://staging.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

<Warning>
  As chaves de API são geradas automaticamente pelo sistema e são exibidas apenas uma vez quando criadas. Se você perder sua chave, precisará criar uma nova e revogar a antiga.
</Warning>

## Usando Sua Chave de API

Inclua sua chave de API em toda requisição usando o cabeçalho `X-Api-Key`:

```bash theme={null}
X-Api-Key: sua-chave-de-api-aqui
```

### Exemplo de Requisição

```bash theme={null}
curl -X GET "https://data-api-dev.voxfi.com.br/v1/data/events" \
  -H "X-Api-Key: sua-chave-de-api-aqui"
```

## Boas Práticas de Segurança

### ✅ Faça

**1. Armazene Chaves de API com Segurança**

Nunca codifique chaves de API diretamente no seu código-fonte. Use variáveis de ambiente ou gerenciamento seguro de segredos:

<CodeGroup>
  ```javascript JavaScript - Variáveis de Ambiente theme={null}
  // 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-dev.voxfi.com.br/v1/data/events', {
    headers: {
      'X-Api-Key': apiKey
    }
  });
  ```

  ```python Python - Variáveis de Ambiente theme={null}
  # arquivo .env (nunca commite isso!)
  VOXFI_API_KEY=sua-chave-de-api-aqui

  # No seu código
  import os
  from dotenv import load_dotenv

  load_dotenv()
  api_key = os.getenv('VOXFI_API_KEY')

  headers = {
      'X-Api-Key': api_key
  }
  ```

  ```bash Bash - Variáveis de Ambiente theme={null}
  # Exporte no seu shell
  export VOXFI_API_KEY="sua-chave-de-api-aqui"

  # Use em scripts
  curl -H "X-Api-Key: $VOXFI_API_KEY" \
    https://data-api-dev.voxfi.com.br/v1/data/events
  ```
</CodeGroup>

**2. Use Serviços de Gerenciamento de Segredos**

Para aplicações em produção, use serviços dedicados de gerenciamento de segredos:

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

**3. Rotacione Chaves Regularmente**

* 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)

**4. Restrinja Permissões das Chaves**

Ao criar chaves de API, configure:

* **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

**5. Monitore o Uso das Chaves**

* 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

**1. Nunca Commite Chaves de API no Controle de Versão**

```bash theme={null}
# ❌ RUIM - Nunca faça isso!
const API_KEY = "voxfi_abc123xyz789";

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

Sempre adicione arquivos `.env` e quaisquer arquivos contendo chaves de API ao `.gitignore`:

```gitignore theme={null}
# .gitignore
.env
.env.local
.env.*.local
*.key
secrets/
config/secrets.json
```

**2. Não Compartilhe Chaves de API Publicamente**

* 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

**3. Não Codifique Chaves em Código do Lado do Cliente**

Chaves de API nunca devem ser expostas em:

* 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

**4. Não Use a Mesma Chave em Todos os Lugares**

* 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

Use variáveis de ambiente ou arquivos de configuração locais:

```bash theme={null}
# .env.local (não commitado)
VOXFI_API_KEY=sua-chave-dev
```

### Produção

Use gerenciamento de segredos na nuvem:

<CodeGroup>
  ```javascript JavaScript - AWS Secrets Manager theme={null}
  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;
  ```

  ```python Python - Google Cloud Secret Manager theme={null}
  from google.cloud import secretmanager

  client = secretmanager.SecretManagerServiceClient()
  name = "projects/YOUR_PROJECT/secrets/voxfi-api-key/versions/latest"
  response = client.access_secret_version(request={"name": name})
  api_key = response.payload.data.decode("UTF-8")
  ```
</CodeGroup>

### Pipelines CI/CD

Armazene chaves como segredos criptografados na sua plataforma CI/CD:

**GitHub Actions:**

```yaml theme={null}
# .github/workflows/api.yml
env:
  VOXFI_API_KEY: ${{ secrets.VOXFI_API_KEY }}
```

**GitLab CI:**

```yaml theme={null}
# .gitlab-ci.yml
variables:
  VOXFI_API_KEY: $VOXFI_API_KEY  # Configure nas variáveis CI/CD
```

## Rotação de Chaves

Se sua chave de API for comprometida ou você precisar rotacioná-la:

1. Crie uma nova chave de API em [Perfil → Segurança](https://staging.voxfi.com.br/profile) 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

Para maior segurança, configure whitelist de IP ao criar sua chave de API:

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

<Info>
  A whitelist de IP é opcional, mas altamente recomendada para aplicações em produção.
</Info>

## Solução de Problemas

### Erro "unauthorized"

Se você receber um 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"

Se você receber um 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](/pt/quickstart) - Comece com sua primeira requisição à API
* [Referência da API](/pt/reference) - Documentação completa dos endpoints
* [Tratamento de Erros](/pt/errors) - Entenda as respostas de erro da API