Authentication

POST /auth/user

With the anonymous register/login endpoint will get access to call the service without the need for a password. This method is useful for api integration with an application that manage their own users.

If a user with the external id do not exist, new generic user will be registered and will get the access token at the same time. If the external id exists exists, a login will be made. This endpoint is intended for B2B use, where the client does not requiere user-level information, but rather a generic authentication.

Because there will be no password-based authentication, this register/login action will be secured with a Hash-based message authentication protocol, or HMAC.

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

Parameters

Response

X-Sherpa-hmac Example

• Input data

  • https://api.sherpalive.ai/v2/auth/user stripped to /v2/auth/user

  • 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/auth/user
    • Timestamp: 1543257277148
    • Nonce: 10ba816b-7ae5-48b3-b6cc-a042658bf3c7
    • All of the above fields should be joined together as follows:/v2/auth/user:1543257277148:10ba816b-7ae5-48b3-b6cc-a042658bf3c7

Using HMAC-SHA1 implementation and this example private key 1679ebfb-636d-415a-a035-fe55629fd950 the result should be:

* output: DB4E6FC4E6998348EB79D9CB999E77ADCE8C2C3E
* base-64 encoded output: 205vxOaZg0jrednLmZ53rc6MLD4=

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/auth/user:" + 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/auth/user" \
-H  "accept: application/json" \
-H  "Accept-Language: es-ES" \
-H  "Time-Zone: Europe/Madrid" \
-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******" \
-H  "content-type: application/json" \
-d "{
    \"externalId\": \"demo@sherpa.ai\",
    \"name\": \"demo\"
}"

Response sample:

{
    "token": "XXXX-SHERPA-TOKEN-XXXX",
    "type": "basic",
    "expires": :1858915823282,
    "username": "demo"
}

The response HTTP code will be 201 on the first call, performing a registration, and a 200 on the posterior calls, doing a login.