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=="'}