Authentication (HMAC)

Lighthouse API support a HMAC signature scheme for API authentication. The client must send the HMAC signature together with a set of special HTTP headers when making a call that requires API authentication. This ensures that the API call is being made from the stated client and that the data has not been tampered with.

Extra information must be added to the HTTP header in order for this data to be correctly processed:

• x-access-key - the Lighthouse public client_id, identifying you to the Lighthouse api server
• x-timestamp - there is no default value. The current unix time in seconds.
• x-signature - there is no default value. The signature is generated for every request

Every signature has limited lifetime (currently 10s). Therefore it is important that you have your server time synchronized via ntp or other source of precise time.

HMAC-SHA256 Signature

This section describes how to create a signature.

The HMAC must be constructed over the following data:

• The Lighthouse public client_id (provided by us when you enter into the Lighthouse integration program)
• The current request method in uppercase, like: GET, POST, etc.
• The current request uri path in lowercase (without host and query parameters), like: /api/v1/export/1/tickets
• The current request body (in case request don't have a body use empty string)
• The current unix time in seconds (same as you will send in header x-timestamp)

Example Rest Requests

This section shows the steps to sign a request with example Lighthouse credentials.

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

Follow these steps with these credentials to generate the same signature strings in the examples. This can help verify your request generation code. You cannot make actual requests with these example requests.

The following is an example of an Export Tickets request:

GET https://conecto-api.shift4payments.com/api/v1/export/1/tickets?filter[dateTimeFrom]=2018-03-01&filter[dateTimeTo]=2018-03-31

Steps to Sign the Example Request

1. Generate a timestamp. For this example, we'll use the 1530194117.
2. Create a request_method (in uppercase). For this example, we'll use the GET
3. Create a request_path (in lowercase). For this example, we'll use the /api/v1/export/1/tickets
4. Create a request_data (in case request don't have a body use empty string). For this example there will be empty string.
5. Combine string to sign from {client_id}{request_method}{request_path}{request_data}{timestamp}. For this example it would be: 23b08412a29bbe8625967e16c1a41dc9GET/api/v1/export/244/tickets1530737508
6. Generate a HMAC-SHA256 digest from string to sign and client_secret.
7. Create a signature, encode digest with HEX. For this example: b8bc892d56050e4d929be06771222e32e42bc4d5679bb79e6fd3f61f20e15ff5

Javascript code example

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

const timestamp = Math.round(new Date().getTime() / 1000); //1530194117 - unix timestamp in seconds
const requestMethod = 'GET'; //uppercase
const requestPath = '/api/v1/export/1/tickets'; //lowercase
const requestData = ''; //this request don't have a body, so we'll use empty string

const combinedString = CLIENT_ID + requestMethod + requestPath + requestData + timestamp; //23b08412a29bbe8625967e16c1a41dc9GET/api/v1/export/244/tickets1530737508
const digest = CryptoJS.HmacSHA256(combinedString, CLIENT_SECRET);
const signature = CryptoJS.enc.Hex.stringify(digest); //01be9d576867309aba8c29e7b6a719fa7607bdfd26177bfd4ce453450c610126

Final request would look:

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'