Authentication (HMAC)

The Lighthouse API uses HMAC signature authentication to ensure API calls originate from verified clients and that request data hasn't been tampered with.

Overview

HMAC signature scheme provides secure API authentication by requiring clients to sign each request with a cryptographic signature. This ensures both the authenticity of the caller and the integrity of the data.

Required Headers

Every authenticated API request must include these HTTP headers:

Signature Lifetime

Every signature has a limited lifetime of 10 seconds. It is critical that your server time is synchronized via NTP or another precise time source to prevent authentication failures.

HMAC-SHA256 Signature

Signature Components

The HMAC signature must be constructed using the following data in order:

1. Client ID - Your Lighthouse public client_id (provided during integration onboarding)
2. Request Method - HTTP method in uppercase: GET, POST, PATCH, etc.
3. Request Path - URI path in lowercase without host or query parameters
   • Example: /api/v1/export/1/tickets
4. Request Body - The complete request payload (use empty string for GET requests)
5. Timestamp - Current Unix time in seconds (same value sent in x-timestamp header)

Signature Generation Steps

1. Concatenate all components into a single string (no separators)
2. Generate HMAC-SHA256 digest using your client_secret as the key
3. Encode the digest as a hexadecimal string
4. Include the resulting signature in the x-signature header

Example Requests

This section demonstrates signing a request with example Lighthouse credentials. Follow these steps to verify your implementation.

Example Credentials:

• client_id: 23b08412a29bbe8625967e16c1a41dc9
• client_secret: de17f1f0-4816-157b-97ae-eb4b0f656a1f

Example GET Request

Signing an Export Tickets API call:

Implementation

JavaScript Example

const CLIENT_ID = '23b08412a29bbe8625967e16c1a41dc9';
const CLIENT_SECRET = 'de17f1f0-4816-157b-97ae-eb4b0f656a1f';

// Generate current timestamp in seconds
const timestamp = Math.round(new Date().getTime() / 1000);

// Request details
const requestMethod = 'GET'; // uppercase
const requestPath = '/api/v1/export/1/tickets'; // lowercase
const requestData = ''; // empty string for GET requests

// Combine all components
const combinedString = CLIENT_ID + requestMethod + requestPath + requestData + timestamp;
// Result: 23b08412a29bbe8625967e16c1a41dc9GET/api/v1/export/244/tickets1530737508

// Generate HMAC-SHA256 signature
const digest = CryptoJS.HmacSHA256(combinedString, CLIENT_SECRET);
const signature = CryptoJS.enc.Hex.stringify(digest);
// Result: 01be9d576867309aba8c29e7b6a719fa7607bdfd26177bfd4ce453450c610126

Complete cURL Request

curl -X GET \
  'https://conecto-api.shift4payments.com/api/v1/export/244/tickets?filter[dateTimeFrom]=2018-03-01&filter[dateTimeTo]=2018-03-31' \
  -H 'Content-Type: application/json' \
  -H 'x-access-key: 23b08412a29bbe8625967e16c1a41dc9' \
  -H 'x-signature: 01be9d576867309aba8c29e7b6a719fa7607bdfd26177bfd4ce453450c610126' \
  -H 'x-timestamp: 1530737508'

Best Practices