Authentication
All calls to the indexing API are authenticated by signing the request using HMAC with SHA384 as the hash function. Your REST API key is used to calculate the signature. The signature must be calculated as described on this page.
To calculate a signature for your request implement the following algorithm in your application.
Determine the following information about your request:
- HTTP method used, e.g. "PUT"
- URL path, e.g. "/v2/batch"
- Query string, e.g. "test=1"
- Secured headers, in order:
- X-KLEVU-TIMESTAMP, e.g. "2023-06-19T00:00:00.000Z"
- ⚠️ The timestamp validation window is set to 20 minutes. Timestamp values provided by the merchant will be considered valid if they fall within a range of 10 minutes in the past and 10 minutes in the future.
- X-KLEVU-APIKEY, e.g. "klevu-1234567890"
- X-KLEVU-AUTH-ALGO, e.g. "HmacSHA384"
- This must match exactly including case.
- Content-Type, e.g. "application/json"
- Request body, e.g. "{}"
- This must be the exact request body that will be sent to the API.
Construct a string containing:
For example, using the data from above:
In the previous example, note the case of the header keys as well as the data. The X-KLEVU- header keys are expected in upper case and "Content-Type" must match as well.
Calculate the binary signature bytes using the HMAC algorithm with SHA384 as the hash function. Use your REST API key as the secret:
Next base64 encode the byte to get your signature.
Set the Authorization header on your request to "Bearer <signature>". Substitute the content of the signature variable in place of "<signature>".
For this example, the full request would be:
Included below is a sample Postman collection demonstrating the process of generating HMAC signatures for batch requests of records.
The above file comprises a sample batch request. Upon importing the collection, you'll find a pre-request script that dynamically generates a signature tailored to the submitted request. Within this batch request, a sample category record is included.
This file lists the environment variables necessary for signature generation. Upon import, we recommend updating the values for the following variables: apiKey and restAuthKey with your respective JS API Key and REST API Key. For guidance on obtaining API Keys, please refer to this article.
