The ZealiD Developer Hub

Welcome to the ZealiD developer hub. You'll find comprehensive guides and documentation to help you start working with ZealiD as quickly as possible, as well as support if you get stuck. Let's jump right in!

About HMAC authentication



Be Aware!

  • curly braces represent variables, do not include curly braces verbatim

HMAC - hash-based message authentication code

HMAC is computed as follows:
HTTP 'Authorization' header value is set to: 'HMAC {hmac_string}'

  • {hmac_string} is: 'client_id="{client_id}",ts="{ts}",nonce="{nonce}",signature="{signature}"'
    • client_id is your ZealiD Client ID
    • ts is UNIX timestamp (integer), for replay and other attack vector mitigation
      must be accurate and generated at the time the request is made
      see Wiki
    • nonce is a random string to prevent replay attacks
      64 characters are recommended, and base64 encoding can for example be used
    • signature is the HMAC signature, computed using SHA512 and base64 encoded
      Signature is computed on the following string (let's call it auth_string)
      auth_string: '{client_id}{nonce}{ts}{request_string}{payload}'
      • client_id, nonce and ts are as described above
      • request_string is '{request_method} {full_path}'
        • request_method is the HTTP request method in capitals, e.g. GET, POST, etc.
        • full_path is HTTP path with base URL excluded, e.g. '/mediator/api/get_token'; if there are any query parameters, they must be included in full, and must exactly match the URL you are requesting the resource with, exactly; e.g. '/mediator/api/something?param=1'
        • example of request_string: 'GET /mediator/api/get_token'
      • payload is the body of your POST request, if any; this is empty string if no body is sent
    • HMAC signature is then computed as:
      BASE64(HMAC-SHA512(client_secret, auth_string))


Sample header with HMAC

'Authorization': 'HMAC client_id="someclient",ts="1616494592",nonce="G9aGfYcjqMtxUIxbsQAcEHQlaba7cFBrZjknC74qEjA",signature="mx1NJbC0Erj4a+Ojiscf4gxzdDARIm9lEofn3D6I7YswQPCSQY9dx8nspek14ZJuLTlW6IyaH7oSYbIweFzS6A=="'}

Updated 5 months ago

About HMAC authentication

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.