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

# API Security

> This page provides important information about the details you need to know before making API requests.

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

```ini theme={null}
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**) 🔒:

```ini theme={null}
X-Signature = HMAC_SHA256(secret, dataToSign)
```

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

<Warning>
  ⚠️ Please ask us **HMAC Secret** before making your first API call.
</Warning>

### What if not used?

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

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

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

<Card title="Security Considerations" icon="shield-halved">
  * 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 ⛔.
</Card>

<Card title="Example Headers" icon="table-list">
  ```ini theme={null}
  X-Signature: 75c759570bbb5dfd40136cffd3dbaa51b28d4620e51359161686790adcc53bea
  X-Timestamp: 1752751106704
  X-Nonce: 684a0dca-bd6a-4056-a449-2567f9847f9c
  X-Idempotency-Key: 777edc03-ad49-4c17-be6b-9baf05a1b9e0
  ```
</Card>

### Summary Table 📊

<Icon icon="table-cells" size={32} />

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