Authentication and Authorization

Overview

Leanafy APIs use HMAC validation for secure authentication. Each API request must be signed using an API Key and API Secret provided by Leanafy. The API Secret must be stored securely and should never be exposed in client-side applications.

Authorization Headers

Each API request must include the following headers:

X-API-Key: Your API Key issued by Leanafy.

X-Signature: HMAC-SHA256 signature generated using the request details and signed by the API Secret.

X-Timestamp: Current Unix timestamp.

The X-Timestamp is used to prevent replay attacks, where an attacker could intercept and reuse a previously valid request to gain unauthorized access. By ensuring that each request includes a fresh timestamp (typically in Unix epoch format), the server can reject requests with outdated timestamps or those that have already been used. This enhances security by making it difficult for malicious actors to reuse intercepted API requests.

What is an API Secret and Why Must It Be Stored Securely?

An API Secret is a private key issued alongside an API Key to authenticate requests made to Leanafy’s APIs. It is used in HMAC (Hash-based Message Authentication Code) validation to generate a digital signature (X-Signature) for each request, ensuring the integrity and authenticity of the communication.

Why Must It Be Stored Securely?

Prevents Unauthorized Access – If exposed, malicious actors could use the API Secret to sign requests and gain unauthorized access to your data.

Protects Data Integrity – The API Secret ensures that requests are legitimate and haven't been tampered with.

Maintains System Security – If compromised, attackers could perform unauthorized operations like creating, modifying, or deleting data in Leanafy.

💡 Best Practices for Security:

Never expose the API Secret in front-end applications or public repositories.

Store it in a secure environment, such as an environment variable or a secrets manager.

Rotate keys periodically to minimize security risks.

Generating X-Signature and X-Timestamp

The X-Signature is calculated using:

HTTP Method (e.g., GET, POST)

Path with query parameters (e.g., /v1/order?a=b)

Current Unix timestamp (to be used as X-Timestamp)

Request body (if present)

The string to sign follows this format:

<HTTP_METHOD>\n<PATH_WITH_QUERY>\n<TIMESTAMP>\n<BODY>

Then, an HMAC-SHA256 signature is generated using the API Secret.

Postman

Authenticating requests using Postman

A preprocessor script is required to calculate the signature and timestamp before making API requests. Below is a sample script for Postman:

Java

Authenticating requests using Java

Below is a Java version of the preprocessor script that calculates the HMAC-SHA256 signature and attaches the required headers. This example uses Java 11's built-in HttpClient for sending an API request.

Explanation:

Environment Variables & Timestamp

The API key and secret are retrieved (via System.getenv) and the current Unix timestamp is generated by dividing the current milliseconds by 1000.

String to Sign
The string is constructed by concatenating:

HTTP method

API endpoint path (with query parameters)

Timestamp

Request body (if present)
Each component is separated by a newline (\n).

HMAC-SHA256 Signature Calculation
Using Java's Mac and SecretKeySpec, the code calculates the HMAC-SHA256 signature from the string to sign and converts the resulting byte array to a hexadecimal string.

Building and Sending the API Request
The example uses Java 11’s HttpClient to create and send an HTTP POST request. The required headers (X-API-Key, X-Timestamp, and X-Signature) are attached to the request.

Replace the placeholder values and the endpoint URL as needed for your integration with Leanafy's APIs.

Overview#

Authorization Headers#

What is an API Secret and Why Must It Be Stored Securely?#

Generating X-Signature and X-Timestamp#

Postman#

Java#

Explanation:#

Overview

Authorization Headers

What is an API Secret and Why Must It Be Stored Securely?

Generating X-Signature and X-Timestamp

Postman

Java

Explanation: