๐งฉ This API leverages a robust security mechanism involving HMAC-based request signing, timestamping, unique request identification (nonce), and idempotency keys. These mechanisms collectively ensure the integrity, authenticity, and non-replayability of client requests, as well as safe handling of duplicate submissions.๐ This documentation explains each mechanism, their purposes, and how to implement the required client logic (e.g., in Postman or custom API clients).
๐ An HMAC (Hash-based Message Authentication Code) is a cryptographic signature generated using a shared secret and the request data. It ensures that the request cannot be tampered with, and its sender can be authenticated.
The client constructs a string to sign, concatenating the HTTP method, full request path (including query), current timestamp in epoch milliseconds, and resolved request body ๐งพ:
Anti-Replay ๐: Further prevents request replay by uniquely identifying each request. Even if method, URI, and body are the same, the nonce will differ.
๐ชช A unique identifier (UUID v4) for each request, enabling the server to recognize and safely ignore duplicate submissions (e.g., from retrying a POST request).
The secret used for HMAC must never be shared or exposed in client code or documentation ๐.
Always use HTTPS to prevent man-in-the-middle attacks ๐.
Servers enforce a maximum allowable time skew for the X-Timestamp and reject used/replayed X-Nonce or X-Idempotency-Key values within a certain window โ.
