Authentication

POST /authenticate

The client must send the HMAC signature, along with a set of special HTTP headers, when making the request 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 with some extra HTTP headers, in order for this data to be correctly processed:

The public apikey provided by Sherpa.ai that identifies you to the API server
The private apikey corresponding to the previous public key
URL encoded string representation of any GET variable parameters

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.

Headers

Request Header	Description
X-Sherpa-apikey	The public API key
X-Sherpa-timestamp	The current UTC Unix timestamp in miliseconds
X-Sherpa-nonce	A random string (UUID recommended) in form of a nonce, in order to guarantee that two requests made at the same time have different signatures
X-Sherpa-hmac	base-64 enconded HMAC signature, computed from `BASE64(HMAC-SHA1(private-key, {GET request queryParams}:{timestamp}:{nonce}))`

Response

Code	Name	Description
204	No Content	On login success
403	Forbidden
409	Conflict
500	Internal Server Error

Header Response:

Field	Type	Value
Authorization	String	User access token

X-Sherpa-hmac Example

Input data
- https://api.sherpalive.ai/v2/authenticate stripped to /v2/authenticate
- Header parameters will be involved in the HMAC header itself:
  - UTC unix timestamp in miliseconds as (X-Sherpa-timestamp)
  - Nonce (X-Sherpa-nonce)
- Given the following data:
  - Resource URL: /v2/authenticate
  - Timestamp: 1543257277148
  - Nonce: 10ba816b-7ae5-48b3-b6cc-a042658bf3c7
  - All of the above fields should be joined together as follows:/v2/authenticate:1543257277148:10ba816b-7ae5-48b3-b6cc-a042658bf3c7

A full example of the registration request would be as follows:

// Pre-request Script in Postman

var moment = require('moment');
var timestamp = moment.utc().valueOf();

var nonce = "randomUUID";

var signatureRawData  = "/v2/authenticate:" + timestamp + ":" + nonce;

var privateKey = "privateKey";   // Private key provided by Sherpa

var hash = CryptoJS.HmacSHA1(signatureRawData, privateKey);
var hashInBase64 = CryptoJS.enc.Base64.stringify(hash);  

pm.globals.set("Sherpa-hmac", hashInBase64);
pm.globals.set("Sherpa-timestamp", timestamp);
pm.globals.set("Sherpa-nonce", nonce);

Request sample:

curl -X POST "https://api.sherpalive.ai/v2/authenticate" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \

Header Response Sample:

 Authorization :XXXX-SHERPA-TOKEN-XXXX