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 fromBASE64(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
- Resource URL:
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