Authentication

HMAC-SHA1-based authentication is the authentication method of the Sherpa.ai Custom Content Recommendation API.

The client must send the HMAC signature, along with a set of special HTTP headers, when making a call to an API endpoint. This ensures that the API call is being made from the stated client and that the data has not been tampered with.

The HMAC must be constructed over the following data:

• The private API Key provided by Sherpa.ai (which is companion to the public key)
• The current UTC Unix timestamp
• A nonce to guarantee that two requests made at the same time have different signatures
• URL encoded string representation of any GET variable parameters

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

X-Sherpa-hmac is the signature computed from your request URI, without protocol, and host + ":" + the timestamp + ":" + the nonce.

Every signature has a limited lifetime of 10 seconds. Therefore, it is important that you have your server time synchronized via NTP or another precise time source.

Example

Imagine you want to make a call to the following URL:

https://recom.sherpa.ai/v2/recomm/items/9346

The input to the signing method would contain:

• "/v2/recomm/items/9346"
• The current UTC Unix timestamp in miliseconds (X-Sherpa-timestamp)
• A random string (X-Sherpa-nonce)

With the private key: "f70a907a-9160-11eb-a8b3-0242ac130003"

HMAC-SHA1(private_key, "/v2/recomm/items/9346:1543257277148:10ba816b-7ae5-48b3-b6cc-a042658bf3c7")

HMAC-SHA1: "091908d88f9335499a6d98c99eca852a515d43a9"

HMAC-SHA1 base64 encoded: "CRkI2I+TNUmabZjJnsqFKlFdQ6k="

Headers:

let path = "/v2/recomm/items/9346";
let timestamp = 1543257277148;
let nonce = "10ba816b-7ae5-48b3-b6cc-a042658bf3c7";
let signatureRawData = path + ":" + timestamp + ":" + nonce;
let secret = "f70a907a-9160-11eb-a8b3-0242ac130003";
let hash = CryptoJS.HmacSHA1(signatureRawData, secret);
let hmacSignature = CryptoJS.enc.Base64.stringify(hash);

Parameters

All the parameters passed to the API in POST and PUT methods should be sent in application/json format.