Authentication Guide

All requests to the Hubby eSIM API must be authenticated using HMAC-SHA256 signatures. This guide explains how to properly authenticate your requests.

API Endpoints

Before making any requests, ensure you're using the correct API endpoint:

• Production: https://api.hubbyesim.com/api - For live applications
• Staging: https://api-staging.hubby.dev/api - For testing and development

Required Headers

Every API request must include these authentication headers:

x-api-key: YOUR_API_KEY
x-timestamp: CURRENT_TIMESTAMP_IN_MS
x-signature: HMAC_SIGNATURE

Generating the HMAC Signature

The signature is generated by:

1. Concatenating the timestamp (in milliseconds), HTTP method, and full request path (including query parameters if present)
2. Creating an HMAC-SHA256 hash using your secret key
3. Converting the hash to a hexadecimal string

For example, for a GET request to /api/bookings?perPage=10 at timestamp 1715558400000:

• Payload would be: 1715558400000GET/api/bookings?perPage=10

Example Implementation

const crypto = require('crypto');

function generateHeaders(method, path, timestamp) {
  // Ensure timestamp is a string and in milliseconds
  const ts = String(timestamp);
  
  // Create the payload string - include query parameters if present
  const payload = ts + method + path;
  
  // Generate HMAC signature
  const signature = crypto
    .createHmac('sha256', process.env.HUBBY_API_SECRET)
    .update(payload)
    .digest('hex');

  // Return all required headers
  return {
    'x-api-key': process.env.HUBBY_API_KEY,
    'x-timestamp': ts,
    'x-signature': signature,
    'Content-Type': 'application/json'
  };
}

Python Implementation

import hmac
import hashlib
import time
import os

def generate_headers(method, path):
    # Get current timestamp in milliseconds
    timestamp = str(int(time.time() * 1000))
    
    # Create payload string - include query parameters if present
    payload = timestamp + method + path
    
    # Generate HMAC signature
    signature = hmac.new(
        os.environ['HUBBY_API_SECRET'].encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Return headers dictionary
    return {
        'x-api-key': os.environ['HUBBY_API_KEY'],
        'x-timestamp': timestamp,
        'x-signature': signature,
        'Content-Type': 'application/json'
    }

Important Notes

1. Timestamp Format

   • Use Unix timestamp in milliseconds (e.g., 1715558400000)
   • Must be within 400 minutes of current time
   • Cannot be in the future

2. Request Path

   • Include the full path starting with /api
   • MUST include query parameters if present
   • Example: /api/bookings?perPage=10

3. API Keys

   • Keep your secret key secure
   • Never expose it in client-side code
   • Keys expire after 1 year
   • Contact support for key rotation

Common Issues

Invalid Signature

If you receive a 401 error with "Invalid signature", check:

1. Timestamp is in milliseconds
2. Query parameters are included in signature calculation
3. Proper path formatting
4. Correct concatenation order
5. Secret key validity

Request Timestamp Expired

If you receive a "Request timestamp expired" error:

1. Ensure your server's clock is synchronized
2. Verify timestamp is in milliseconds
3. Check if timestamp is within 400 minutes

Example Request

const timestamp = Date.now().toString();
const method = 'GET';
const path = '/api/bookings?perPage=10';

const headers = generateHeaders(method, path, timestamp);

// Use staging for development, production for live
const API_BASE_URL = process.env.NODE_ENV === 'production' 
  ? 'https://api.hubbyesim.com'
  : 'https://api-staging.hubby.dev';

const response = await fetch(`${API_BASE_URL}/api/bookings?perPage=10`, {
  method: method,
  headers: headers
});

Security Best Practices

1. Environment Variables

   • Store API keys in environment variables
   • Never commit keys to version control
   • Use different keys for development and production

2. Key Management

   • Rotate keys periodically
   • Revoke compromised keys immediately
   • Monitor API usage for suspicious activity

3. Request Validation

   • Validate all input parameters
   • Use HTTPS for all requests
   • Implement rate limiting

Getting Help

If you're having trouble with authentication:

1. Check our troubleshooting guide
2. Review the API reference
3. Contact support@hubbyesim.com