Skip to main content

​
Overview

All requests to the VoxFi Public API require authentication using an API key. Your API key identifies you to the API and grants access to your account resources.

​
Getting Your API Key

To create an API key:
  1. Log in to your VoxFi account at https://voxfi.com.br/profile
  2. Navigate to Profile → Security
  3. Click on Create API Key or Create New API Key
  4. Configure your API key settings:
    • Name (required): Give your API key a descriptive name (e.g., “Mobile App”, “Production Server”)
    • Expiration Date (required): Set when the API key should expire
    • Permissions (optional): Select specific permissions for the key. If none are selected, all permissions will be granted:
      • Read orders
      • Create orders
      • Cancel orders
      • Read positions
      • Read wallet
    • Allowed IPs (optional): Specify IP addresses allowed to use this key (comma-separated). If empty, all IPs will be allowed
  5. Click Create to generate your API key
  6. Copy your API key immediately - it will be automatically generated and displayed only once
  7. Store it securely using the best practices outlined below
API keys are automatically generated by the system and are only shown once when created. If you lose your key, you’ll need to create a new one and revoke the old one.

​
Using Your API Key

Include your API key in every request using the X-Api-Key header: 
X-Api-Key: your-api-key-here

​
Example Request

curl -X GET "https://data-api.voxfi.com.br/v1/data/events" \
  -H "X-Api-Key: your-api-key-here"

​
Security Best Practices

​
✅ Do’s

1. Store API Keys Securely Never hardcode API keys in your source code. Use environment variables or secure secret management: 
// .env file (never commit this!)
VOXFI_API_KEY=your-api-key-here

// In your code
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
  }
});
2. Use Secret Management Services For production applications, use dedicated secret management services:
  • AWS Secrets Manager / AWS Parameter Store
  • Google Cloud Secret Manager
  • Azure Key Vault
  • HashiCorp Vault
  • 1Password Secrets Automation
  • GitHub Secrets (for CI/CD)
3. Rotate Keys Regularly
  • Generate new API keys periodically
  • Revoke old keys that are no longer in use
  • Use different keys for different environments (development, staging, production)
4. Restrict Key Permissions When creating API keys, configure:
  • Name: Use descriptive names to identify the purpose of each key
  • IP Whitelisting: Restrict API key usage to specific IP addresses (comma-separated)
  • Permissions: Select only the permissions your application needs (read orders, create orders, cancel orders, read positions, read wallet)
  • Expiration: Set expiration dates for temporary access
5. Monitor Key Usage
  • Regularly review API key usage logs
  • Set up alerts for unusual activity
  • Monitor for unauthorized access attempts

​
❌ Don’ts

1. Never Commit API Keys to Version Control 
# ❌ BAD - Never do this!
const API_KEY = "voxfi_abc123xyz789";

# ✅ GOOD - Use environment variables
const API_KEY = process.env.VOXFI_API_KEY;
Always add .env files and any files containing API keys to .gitignore: 
# .gitignore
.env
.env.local
.env.*.local
*.key
secrets/
config/secrets.json
2. Don’t Share API Keys Publicly
  • Never post API keys in forums, chat rooms, or public repositories
  • Don’t include keys in screenshots or documentation examples
  • Avoid sending keys via email or unencrypted messages
3. Don’t Hardcode Keys in Client-Side Code API keys should never be exposed in:
  • Browser JavaScript
  • Mobile app code that can be decompiled
  • Public repositories
  • Client-side configuration files
4. Don’t Use the Same Key Everywhere
  • Use separate keys for different applications
  • Use separate keys for different environments
  • Rotate keys when team members leave

​
Environment-Specific Storage

​
Development

Use environment variables or local configuration files: 
# .env.local (not committed)
VOXFI_API_KEY=your-dev-api-key

​
Production

Use cloud secret management: 
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;

​
CI/CD Pipelines

Store keys as encrypted secrets in your CI/CD platform: GitHub Actions: 
# .github/workflows/api.yml
env:
  VOXFI_API_KEY: ${{ secrets.VOXFI_API_KEY }}
GitLab CI: 
# .gitlab-ci.yml
variables:
  VOXFI_API_KEY: $VOXFI_API_KEY  # Set in CI/CD variables

​
Key Rotation

If your API key is compromised or you need to rotate it:
  1. Create a new API key in Profile → Security with the same or updated settings
  2. Copy the new automatically generated API key
  3. Update all applications using the old key
  4. Revoke the old API key
  5. Verify all applications are working with the new key
  6. Monitor for any unauthorized access attempts

​
IP Whitelisting

For enhanced security, configure IP whitelisting when creating your API key:
  1. Go to Profile → Security
  2. When creating your API key, enter allowed IP addresses in the “Allowed IPs” field (comma-separated, e.g., 192.168.1.1, 10.0.0.1)
  3. Only requests from whitelisted IPs will be accepted
  4. If left empty, all IPs will be allowed
  5. To update IPs for an existing key, you’ll need to create a new key with updated IPs and revoke the old one
IP whitelisting is optional but highly recommended for production applications.

​
Troubleshooting

​
”unauthorized” Error

If you receive an unauthorized error:
  1. Verify your API key is correct
  2. Check that the X-Api-Key header is included in your request
  3. Ensure your API key hasn’t expired
  4. Verify your API key is enabled
  5. Check if IP whitelisting is blocking your request

​
”ip not allowed” Error

If you receive an ip not allowed error:
  1. Check your current IP address
  2. Verify your IP is in the whitelist for your API key
  3. Update the whitelist in Profile → Security if needed

​
Additional Resources