[TRANSLATION ERROR] There are no messages for this key

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 HeaderDescription
X-Sherpa-apikeyThe public API key
X-Sherpa-timestampThe current UTC Unix timestamp in miliseconds
X-Sherpa-nonceA 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-hmacbase-64 enconded HMAC signature, computed from
BASE64(HMAC-SHA1(private-key, {GET request queryParams}:{timestamp}:{nonce}))

Response

CodeNameDescription
204No ContentOn login success
403Forbidden
409Conflict
500Internal Server Error

Header Response:

FieldTypeValue
AuthorizationStringUser 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