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

# API Authentication & Requests

> Learn how to authenticate and make requests to the Vantio API

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

1. Log in to your [Vantio Dashboard](https://dash.vantio.app)
2. Navigate to **Settings** → **API Keys**
3. Create a new API key or copy an existing one
4. Your API key starts with `sk_`

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

## Authentication Header

Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer sk_your_secret_key_here
```

## Making API Requests

### Using cURL

```bash theme={null}
curl -X GET "https://vantio.app/api/v1/users" \
  -H "Authorization: Bearer sk_your_secret_key_here"
```

### Using JavaScript (Fetch API)

```javascript theme={null}
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)

```javascript theme={null}
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)

```python theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
// 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

## Handling Errors

Always check the response status and handle errors appropriately:

```javascript theme={null}
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

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

## Environment Variables

Store your API key as an environment variable:

```bash theme={null}
# .env file
VANTIO_API_KEY=sk_your_secret_key_here
```

```javascript theme={null}
// Access in your code
const API_KEY = process.env.VANTIO_API_KEY;
```