Authentication

The vFairs API uses industry-standard authentication methods to ensure secure access to your event data. We support OAuth 2.0 with client credentials flow for server-to-server integrations.

Authentication Methods

OAuth 2.0 (Recommended)

OAuth 2.0 with client credentials flow is the recommended authentication method for server-to-server integrations.

Security Scheme Type	HTTP
HTTP Authorization Scheme	Bearer
Bearer Format	OAuth

Getting Your Credentials

Steps to Obtain "App Key" & "App Secret" for Access Token:

Log in to your event backend and navigate to Event Setup.
Go to the API tab and click to open it.
Click the Generate Secret button on the right side.
Enter a name for your secret key (e.g., "Secret Key" or "ABC") and click the Update button.
Use the App Key and Secret Key to obtain the access token.

For more details, refer to the following image:

Important: Store your credentials securely and never expose them in client-side code or public repositories.

Obtaining an Access Token

Make a POST request to the token endpoint:

Request:

curl -X POST "https://api.vfairs.com/v1/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:events read:attendees read:sessions"
}

Using the Access Token

Include the access token in the Authorization header of your API requests:

curl -X GET "https://api.vfairs.com/v1/events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

API Key Authentication

For simpler integrations, you can use API key authentication by including your API key in the request headers.

curl -X GET "https://api.vfairs.com/v1/events" \
  -H "X-API-Key: YOUR_API_KEY"

Token Management

Token Expiration

Access tokens expire after 1 hour (3600 seconds). Your application should:

Check the expires_in field in the token response
Refresh tokens before they expire
Handle 401 Unauthorized responses by obtaining a new token

Token Refresh

Since we use the client credentials flow, simply request a new token when the current one expires:

async function getAccessToken() {
  const response = await fetch('https://api.vfairs.com/v1/auth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      'grant_type': 'client_credentials',
      'client_id': process.env.VFAIRS_CLIENT_ID,
      'client_secret': process.env.VFAIRS_CLIENT_SECRET,
    }),
  });
  
  const data = await response.json();
  return data.access_token;
}

Scopes

The vFairs API uses scopes to control access to different resources:

Scope	Description
`read:events`	Read access to events and event details
`read:attendees`	Read access to attendee information
`read:sessions`	Read access to session data
`write:events`	Write access to create and update events
`write:attendees`	Write access to manage attendee data

Security Best Practices

Credential Storage

Store credentials as environment variables
Use secure credential management systems in production
Never commit credentials to version control

Token Security

Use HTTPS for all API requests
Implement token refresh logic
Monitor for unauthorized access

Rate Limiting

Respect rate limits to avoid being blocked
Implement exponential backoff for retries
Cache responses when possible

Error Handling

Authentication Errors

Status Code	Error Code	Description
`401`	`INVALID_CREDENTIALS`	Invalid client ID or secret
`401`	`EXPIRED_TOKEN`	Access token has expired
`401`	`INVALID_TOKEN`	Malformed or invalid token
`403`	`INSUFFICIENT_SCOPE`	Token lacks required permissions

Example Error Response

{
  "status": "error",
  "code": "INVALID_CREDENTIALS",
  "message": "The provided client credentials are invalid",
  "details": {
    "timestamp": "2024-01-15T14:30:00Z",
    "request_id": "req_abc123"
  }
}

Code Examples

Python

import requests
import os

def get_access_token():
    url = "https://api.vfairs.com/v1/auth/token"
    data = {
        "grant_type": "client_credentials",
        "client_id": os.getenv("VFAIRS_CLIENT_ID"),
        "client_secret": os.getenv("VFAIRS_CLIENT_SECRET")
    }
    
    response = requests.post(url, data=data)
    response.raise_for_status()
    
    return response.json()["access_token"]

def make_api_request(endpoint):
    token = get_access_token()
    headers = {"Authorization": f"Bearer {token}"}
    
    response = requests.get(f"https://api.vfairs.com/v1/{endpoint}", headers=headers)
    response.raise_for_status()
    
    return response.json()

Node.js

const axios = require('axios');

async function getAccessToken() {
  const response = await axios.post('https://api.vfairs.com/v1/auth/token', {
    grant_type: 'client_credentials',
    client_id: process.env.VFAIRS_CLIENT_ID,
    client_secret: process.env.VFAIRS_CLIENT_SECRET,
  }, {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
  });
  
  return response.data.access_token;
}

async function makeApiRequest(endpoint) {
  const token = await getAccessToken();
  
  const response = await axios.get(`https://api.vfairs.com/v1/${endpoint}`, {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });
  
  return response.data;
}

Testing Authentication

You can test your authentication setup using curl:

# Test token endpoint
curl -X POST "https://api.vfairs.com/v1/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

# Test API access
curl -X GET "https://api.vfairs.com/v1/events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Support

If you encounter authentication issues:

Verify your credentials are correct
Check that your account has API access enabled
Review the error response for specific details
Contact integrations@vfairs.com for assistance