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:
| Request Header | Description |
|---|---|
| X-Sherpa-apikey | The public API key |
| X-Sherpa-timestamp | The current UTC Unix timestamp |
| X-Sherpa-nonce | A random string (UUID recommended) |
| X-Sherpa-hmac | The HMAC encoded in base64 |
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: "1679ebfb-636d-415a-a035-fe55629fd950"
HMAC-SHA1(private_key, "/v2/recomm/items/9346:1543257277148:10ba816b-7ae5-48b3-b6cc-a042658bf3c7")
HMAC-SH1: "548dc33aa78b8e102c57d6e87cce25b01b86bff4"
HMAC-SH1 base64 encoded: "NTQ4ZGMzM2FhNzhiOGUxMDJjNTdkNmU4N2NjZTI1YjAxYjg2YmZmNA=="
Headers:
| Request Header | Description |
|---|---|
| X-Sherpa-apikey | 1679ebfb-636d-415a-a035-fe55629fd950 |
| X-Sherpa-timestamp | 1543257277148 |
| X-Sherpa-nonce | 10ba816b-7ae5-48b3-b6cc-a042658bf3c7 |
| X-Sherpa-hmac | NTQ4ZGMzM2FhNzhiOGUxMDJjNTdkNmU4N2NjZTI1YjAxYjg2YmZmNA== |
Parameters
All the parameters passed to the API in POST and PUT methods should be sent in application/json format.