Liminal supports HMAC authentication on top of IP whitelist security using a trusted SecureAPI app. It ensures that only authorised applications from trusted networks can access Liminal Express APIs, protecting against credential theft and unauthorised access.

You can add an enhanced layer of security using HMAC authentication with a secret key after you have whitelisted the Source IP and Express Server IP addresses of your environment’s API key. The HMAC authentication enforces protection against:

IP spoofing by validating the Source and Express IP addresses using the HMAC signature.
Replay attacks using timestamps (x-timestamp), ensuring signatures cannot be reused.
HMAC signature validation ensures only trusted clients can access headers.

How HMAC secures whitelisted IPs

Hash-based message authentication code (HMAC) is a cryptographic authentication method that generates a signature using a hash function (in this case, SHA-256) and a secret key. The signature ensures the authenticity of the message payload, ensuring whitelisted IP addresses are authorised.

The HMAC secret is generated and added to the client’s server-side Liminal Express SDK environment variables. Owners and Admins can configure the HMAC secret in the following ways:

Liminal Vaults account, and
The environment variable file (.env) of your Liminal Express SDK.

The HMAC signature is applied to the following values:

Parameter	Data Type	Description
`x-origin-ip`	String	The originating IP address of the client application.
`x-express-ip`	String	The IP address of the Liminal Express server.
`timestamp`	String (Unix/Epoch or ISO)	The current timestamp used in the request signature to prevent replay attacks.

Configure HMAC secret

The HMAC secret must be set up for the whitelisted Origin IP and Express IP addresses associated with your API key. It should be added to the client’s SDK environment variables and your Liminal Vaults account.

Parameter	Data Type	Description
`HMAC_SECRET`	String	Shared secret key for HMAC authentication between Liminal Express API and the client application. The key must be 20–64 alphanumeric characters.

Prerequisite

You need to have at least one Source IP and Express IP whitelisted for your environment’s API key to implement HMAC authentication.
Ensure you have the latest version of the Liminal Express SDK.

Step 1: Configure the HMAC secret for your environment

Generate and deploy the HMAC secret in your environment. Please ensure to follow the correct HMAC secret key format. It is a String of 20-64 Alphanumeric characters only.

Choose the HMAC secret key: Please contact your deployment team to assist in generating the key. Contact Liminal Support for any assistance.
Deploy key as an environment variable: Add the HMAC_SECRET as an environment variable file (.env) of your Liminal Express SDK.

Example:
```
HMAC_SECRET = "a1B2c3D4e5F6g7H8i9J0K1L2M3N4O5P6"
```

👍
Tip
Ensure you do not expose the HMAC_SECRET in logs, public repositories, or client-side code.

Step 2: Add key to Liminal Vaults

Add the HMAC secret key to your Liminal Vaults account.

Log in to your Liminal Vaults account.
Navigate to Apps from the left navigation bar.
Click View in the SecureAPI section.
Enter the HMAC secret and click Save.

The pop-up message confirms the action. Close and continue.

📘
Note
The HMAC secret must be entered both in the Liminal Vaults web app and your Liminal Express SDK’s API keys.

You have successfully enhanced the security of your whitelisted Origin IP and Express IP configured in your active API key using HMAC authentication.