Skip to main content

API Authentication

All O2VEND Storefront API requests require authentication using API keys. This guide covers authentication methods and best practices.

Authentication Method​

O2VEND uses API Key authentication via HTTP headers.

Required Header​

All API requests must include the X-O2VEND-SHOPFRONT-API-KEY header:

GET /shopfront/api/v2/products
X-O2VEND-SHOPFRONT-API-KEY: your-api-key-here

Getting Your API Key​

API keys are obtained from the O2VEND Back Office:

  1. Log in to your O2VEND account
  2. Navigate to Settings → API Keys
  3. Create a new API key or use an existing one
  4. Copy the API key (store it securely)

API Key Format​

API keys are typically:

  • 32-64 character strings
  • Alphanumeric with possible hyphens
  • Unique per tenant

Example:

a1b2c3d4-e5f6-7890-abcd-ef1234567890

Making Authenticated Requests​

cURL Example​

curl -X GET "https://your-store.o2vend.com/shopfront/api/v2/products" \
  -H "X-O2VEND-SHOPFRONT-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json"

JavaScript Example​

const apiKey = 'your-api-key-here';
const baseUrl = 'https://your-store.o2vend.com/shopfront/api/v2';

async function fetchProducts() {
  const response = await fetch(`${baseUrl}/products`, {
    method: 'GET',
    headers: {
      'X-O2VEND-SHOPFRONT-API-KEY': apiKey,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data = await response.json();
  return data;
}

Node.js Example​

const axios = require('axios');

const apiClient = axios.create({
  baseURL: 'https://your-store.o2vend.com/shopfront/api/v2',
  headers: {
    'X-O2VEND-SHOPFRONT-API-KEY': 'your-api-key-here',
    'Content-Type': 'application/json'
  }
});

async function getProducts() {
  try {
    const response = await apiClient.get('/products');
    return response.data;
  } catch (error) {
    console.error('API Error:', error.response?.data || error.message);
    throw error;
  }
}

Python Example​

import requests

api_key = 'your-api-key-here'
base_url = 'https://your-store.o2vend.com/shopfront/api/v2'

headers = {
    'X-O2VEND-SHOPFRONT-API-KEY': api_key,
    'Content-Type': 'application/json'
}

response = requests.get(f'{base_url}/products', headers=headers)
data = response.json()

Authentication Errors​

Invalid API Key (401 Unauthorized)​

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

Solutions:

  • Verify API key is correct
  • Check for typos or extra spaces
  • Ensure API key is active in Back Office

Missing API Key (401 Unauthorized)​

{
  "error": "Unauthorized",
  "message": "API key required"
}

Solutions:

  • Include X-O2VEND-SHOPFRONT-API-KEY header
  • Verify header name is correct (case-sensitive)

Expired API Key (401 Unauthorized)​

{
  "error": "Unauthorized",
  "message": "API key expired"
}

Solutions:

  • Generate a new API key in Back Office
  • Update your application with new key

Security Best Practices​

1. Store API Keys Securely​

Never:

  • Commit API keys to version control
  • Hardcode API keys in client-side code
  • Share API keys publicly
  • Include API keys in URLs

Do:

  • Use environment variables
  • Store in secure configuration files
  • Use secret management services
  • Rotate keys regularly

2. Use Environment Variables​

// .env file (not committed)
O2VEND_API_KEY=your-api-key-here

// In code
const apiKey = process.env.O2VEND_API_KEY;

3. Implement Key Rotation​

  • Regularly rotate API keys
  • Update all applications when rotating
  • Revoke old keys after rotation

4. Limit Key Scope​

  • Use different keys for different environments
  • Create keys with minimal required permissions
  • Revoke unused keys

5. Monitor Key Usage​

  • Monitor API key usage in Back Office
  • Set up alerts for unusual activity
  • Review access logs regularly

Checkout Authentication​

For checkout requests, additional authentication may be required:

POST /shopfront/api/v2/checkout
X-O2VEND-SHOPFRONT-API-KEY: your-api-key-here
X-CHECKOUT-SIGNATURE: hmac-signature-here

The checkout signature is generated using HMAC-SHA256:

const crypto = require('crypto');

function generateCheckoutSignature(requestBody, secretKey) {
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(JSON.stringify(requestBody));
  return hmac.digest('base64');
}

Rate Limiting​

API requests are rate-limited. Include proper error handling:

async function makeApiRequest(url, options) {
  try {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      // Rate limited - retry after delay
      const retryAfter = response.headers.get('Retry-After');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeApiRequest(url, options); // Retry
    }
    
    return response;
  } catch (error) {
    // Handle error
    throw error;
  }
}

Testing Authentication​

Test API Key​

# Test authentication
curl -X GET "https://your-store.o2vend.com/shopfront/api/v2/store" \
  -H "X-O2VEND-SHOPFRONT-API-KEY: your-api-key-here"

Verify Response​

Successful authentication returns data:

{
  "id": "store-123",
  "name": "My Store",
  ...
}

Failed authentication returns error:

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

Next Steps​