> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.tarla.io/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`.
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`
```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"
}
```
* 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.
```ini theme={null}
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 |