Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api-docs.iklim.co/llms.txt

Use this file to discover all available pages before exploring further.

โ€‹
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 ๐Ÿ“Š

HeaderValue/FormatPurpose
X-SignatureHexadecimal stringRequest authenticity/integrity
X-TimestampMilliseconds since epochPrevent replay
X-NonceUUID v4Uniqueness/anti-replay
X-Idempotency-KeyUUID v4Idempotency for retries