HMAC authentication

HMAC computation

Before issuing a request, the client must compute a hash-based message authentication code (HMAC) that is unique to that request. The HMAC is computed as follows:

1. A message is assembled by concatenating the following parameters:
   • API Key. This is a unique identifier provided to the client upon registration to use the platform.
   • HTTP request method. GET, POST, DELETE, and so on, as uppercase.
   • HTTP request target. Original request target.
   • Timestamp. Time at which the request was created, UTC in milliseconds from Unix epoch.
   • Nonce. A random, unique identifier, generated by the client.
   • MD5 hash of the HTTP request body.
2. The message is hashed using a SHA256 based HMAC algorithm to produce a signature. The hashing mechanism uses the API secret as a cryptographic key.

   Note: The secret is never communicated across the Internet.

3. The bytes representing the signature are converted to a base64 encoded string.

Authorization header

Each request must include an "Authorization" HTTP header, which includes the computed HMAC and other supporting parameters. The value of the header must be in the following format.

epi-hmac <api-key>:<timestamp>:<nonce>:<hmac>

The parameters comprising this header include:

• API Key. This is a unique identifier provided to the client upon registration to use the platform.
• Timestamp.Time at which the request was created; UTC in milliseconds from Unix epoch.
• Nonce. A random, unique identifier, generated by the client.
• HMAC. The signature computed for the header.

HMAC authentication example with Postman

1. Add the Pre-request Script:
   

   var crypto = require('crypto-js')
   var uuid = require('uuid')
   
   // Update this with your keys first
   var appKey = "yourProvidedAppKey"
   var secret = "yourProvidedSecret"
   
   // Collect data needed for HMAC
   var time = (new Date()).getTime()
   var path = pm.request.url.getPath()
   var bodySignature = CryptoJS.MD5(pm.request.body.toString())
   var nonce = uuid.v4()
   var method = pm.request.method
   
   // Build Message
   var message = appKey+method+path+time+nonce+bodySignature
   console.log("Message",message)
   
   // Sign message and create header
   var hash = crypto.HmacSHA256(message,secret)
   var hashHeader = [
       appKey,
       time,
       nonce,
       CryptoJS.enc.Base64.stringify(hash)
   ].join(':')
   
   // Add Authorization header with computed HMAC to the request
   pm.request.headers.add({
       key: "Authorization",
       value: "epi-hmac "+ hashHeader    
   });

2. Update the appKey and secret in the Pre-request Script with your provided keys.

Last updated: Feb 18, 2022