API Authentication & Requests

Authentication Overview

All Vantio API endpoints require authentication using a Bearer token. Your API key should be included in the Authorization header of every request.

Getting Your API Key

Log in to your Vantio Dashboard
Navigate to Settings → API Keys
Create a new API key or copy an existing one
Your API key starts with sk_

Never expose your API key in client-side code, commit it to version control, or share it publicly. Treat it like a password.

Authentication Header

Include your API key in the Authorization header:

Authorization: Bearer sk_your_secret_key_here

Making API Requests

Using cURL

curl -X GET "https://vantio.app/api/v1/users" \
  -H "Authorization: Bearer sk_your_secret_key_here"

Using JavaScript (Fetch API)

const API_KEY = process.env.VANTIO_API_KEY;

const response = await fetch('https://vantio.app/api/v1/users', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

const data = await response.json();

Using JavaScript (Axios)

const axios = require('axios');

const response = await axios.get('https://vantio.app/api/v1/users', {
  headers: {
    'Authorization': `Bearer ${process.env.VANTIO_API_KEY}`
  }
});

const data = response.data;

Using Python (Requests)

import os
import requests

api_key = os.environ.get('VANTIO_API_KEY')
headers = {
    'Authorization': f'Bearer {api_key}'
}

response = requests.get(
    'https://vantio.app/api/v1/users',
    headers=headers
)

data = response.json()

Request Methods

The Vantio API uses standard HTTP methods:

Method	Usage	Example
`GET`	Retrieve resources	List users, get referral details
`POST`	Create resources	Create referral, create earning
`PUT`	Update resources	Update referral status, update earning

Request Body Format

For POST and PUT requests, send JSON data in the request body:

const response = await fetch('https://vantio.app/api/v1/referrals', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    impression_id: 'imp_123abc',
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com'
  })
});

Query Parameters

Many endpoints support query parameters for filtering and pagination:

// Filter referrals by program and status
const response = await fetch(
  'https://vantio.app/api/v1/referrals?programId=prog_123abc&status=converted&limit=50',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

Response Format

All successful API responses return JSON:

{
  "id": "ref_123abc",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "status": "pending"
}

Error Responses

The API uses standard HTTP status codes:

200 - Success
400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid or missing API key)
404 - Not Found (resource doesn’t exist)

Error responses include a message:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Handling Errors

Always check the response status and handle errors appropriately:

async function fetchUsers() {
  try {
    const response = await fetch('https://vantio.app/api/v1/users', {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'API request failed');
    }
    
    return await response.json();
  } catch (error) {
    console.error('Error fetching users:', error);
    throw error;
  }
}

Rate Limits

The Vantio API enforces rate limits to ensure fair usage. Check response headers for rate limit information:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Remaining requests in current window
X-RateLimit-Reset - Time when the rate limit resets

Best Practices

Store API keys securely - Use environment variables, never hardcode
Handle errors gracefully - Always check response status codes
Use idempotency keys - For POST requests that might be retried
Implement retry logic - For transient failures (with exponential backoff)
Cache responses - When appropriate to reduce API calls

Environment Variables

Store your API key as an environment variable:

# .env file
VANTIO_API_KEY=sk_your_secret_key_here

// Access in your code
const API_KEY = process.env.VANTIO_API_KEY;

Get Started

Essentials

API Authentication & Requests

Authentication Overview

Getting Your API Key

Authentication Header

Making API Requests

Using cURL

Using JavaScript (Fetch API)

Using JavaScript (Axios)

Using Python (Requests)

Request Methods

Request Body Format

Query Parameters

Response Format

Error Responses

Handling Errors

Rate Limits

Best Practices

Environment Variables

​Authentication Overview

​Getting Your API Key

​Authentication Header

​Making API Requests

​Using cURL

​Using JavaScript (Fetch API)

​Using JavaScript (Axios)

​Using Python (Requests)

​Request Methods

​Request Body Format

​Query Parameters

​Response Format

​Error Responses

​Handling Errors

​Rate Limits

​Best Practices

​Environment Variables

Authentication Overview

Getting Your API Key

Authentication Header

Making API Requests

Using cURL

Using JavaScript (Fetch API)

Using JavaScript (Axios)

Using Python (Requests)

Request Methods

Request Body Format

Query Parameters

Response Format

Error Responses

Handling Errors

Rate Limits

Best Practices

Environment Variables