Secure API Request Signing and Idempotency Mechanism

Overview

🧩 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).

1. HMAC Signature (`X-Signature` Header)

What is it?

🔑 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.

Purpose

Integrity 🛡️: Detects if any part of the request (method, URI, body, timestamp) has been altered.
Authentication 🔐: Confirms the request is from a trusted client who knows the secret key.
Anti-Replay ♻️: Tied to a timestamp and unique values, making replay attacks detectable.

How is it used?

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 🧾:

dataToSign = HTTP_METHOD + "|" + PATH_WITH_QUERY + "|" + TIMESTAMP + "|" + BODY

The client generates the HMAC SHA256 signature using the shared secret (kept in a secure vault, never exposed) 🔒:

X-Signature = HMAC_SHA256(secret, dataToSign)

This signature is sent in the request header X-Signature 🚀.

⚠️ Please ask us HMAC Secret before making your first API call.

What if not used?

Client will receive an error message with http status 400 - Bad Request

{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Bad Request",
  "message": "Missing signature, timestamp, or nonce headers",
  "path": "/auth/login"
}

What if signature is not valid?

Client will receive an error message with http status 401 - Unauthorized

{
  "timestamp": "2025-04-14T16:57:50.083970026",
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid request signature",
  "path": "/auth/login"
}

2. Timestamp (`X-Timestamp` Header)

What is it?

⏱️ The Unix timestamp (in milliseconds) at the moment the request is generated.

Purpose

Anti-Replay 🛑: Prevents an attacker from reusing a previously valid request, since the server can enforce strict time windows for valid requests.

How is it used?

The client generates the timestamp just before sending the request and includes it as the X-Timestamp header ⌚.

What if not used?

Client will receive an error message with http status 400 - Bad Request

{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Bad Request",
  "message": "Missing signature, timestamp, or nonce headers",
  "path": "/auth/login"
}

3. Nonce (`X-Nonce` Header)

What is it?

🎲 A nonce is a randomly generated unique identifier (UUID v4) included in each request.

Purpose

Anti-Replay 🔁: Further prevents request replay by uniquely identifying each request. Even if method, URI, and body are the same, the nonce will differ.

How is it used?

The client generates a new UUID v4 for every request and includes it as the X-Nonce header 🎯.

What if not used?

Client will receive an error message with http status 400 - Bad Request

{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Bad Request",
  "message": "Missing signature, timestamp, or nonce headers",
  "path": "/auth/login"
}

What if re-used?

Client will receive an error message with http status 409 - Conflict

{
  "timestamp": "2025-04-14T16:57:21.168927321",
  "status": 409,
  "error": "Conflict",
  "message": "Replay attack detected (nonce reused)",
  "path": "/endpoint/uri/here"
}

4. Idempotency Key (`X-Idempotency-Key` Header)

What is it?

🪪 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).

Purpose

Idempotency 🔂: Guarantees that retrying a request due to network errors will not result in duplicate resource creation or side effects.

How is it used?

The client generates a new UUID v4 for each operation and sends it as the X-Idempotency-Key header 📮.

What if not used?

Client will receive an error message with http status 400 - Bad Request

{
  "timestamp": "2025-04-14T16:26:54.203118461",
  "status": 400,
  "error": "Bad Request",
  "message": "Missing X-Idempotency-Key header",
  "path": "/endpoint/uri/here"
}

What if re-used?

Client will receive an error message with http status 409 - Conflict

{
  "timestamp": "2025-04-14T16:56:28.671809875",
  "status": 409,
  "error": "Conflict",
  "message": "Duplicate request detected (X-Idempotency-Key)",
  "path": "/endpoint/uri/here"
}

Security Considerations

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 ⛔.

Example Headers

X-Signature: 75c759570bbb5dfd40136cffd3dbaa51b28d4620e51359161686790adcc53bea
X-Timestamp: 1752751106704
X-Nonce: 684a0dca-bd6a-4056-a449-2567f9847f9c
X-Idempotency-Key: 777edc03-ad49-4c17-be6b-9baf05a1b9e0

Summary Table 📊

Header	Value/Format	Purpose
X-Signature	Hexadecimal string	Request authenticity/integrity
X-Timestamp	Milliseconds since epoch	Prevent replay
X-Nonce	UUID v4	Uniqueness/anti-replay
X-Idempotency-Key	UUID v4	Idempotency for retries

​Secure API Request Signing and Idempotency Mechanism

​Overview

​1. HMAC Signature (X-Signature Header)

​What is it?

​Purpose

​How is it used?

​What if not used?

​What if signature is not valid?

​2. Timestamp (X-Timestamp Header)

​What is it?

​Purpose

​How is it used?

​What if not used?

​3. Nonce (X-Nonce Header)

​What is it?

​Purpose

​How is it used?

​What if not used?

​What if re-used?

​4. Idempotency Key (X-Idempotency-Key Header)

​What is it?

​Purpose

​How is it used?

​What if not used?

​What if re-used?

Security Considerations

Example Headers

​Summary Table 📊

Secure API Request Signing and Idempotency Mechanism

Overview

1. HMAC Signature (`X-Signature` Header)

What is it?

Purpose

How is it used?

What if not used?

What if signature is not valid?

2. Timestamp (`X-Timestamp` Header)

What is it?

Purpose

How is it used?

What if not used?

3. Nonce (`X-Nonce` Header)

What is it?

Purpose

How is it used?

What if not used?

What if re-used?

4. Idempotency Key (`X-Idempotency-Key` Header)

What is it?

Purpose

How is it used?

What if not used?

What if re-used?

Summary Table 📊