Authentication - Meridian

All API calls use an HMAC authentication strategy with pre-shared API and secret keys.
Sandbox and production environments have different API credentials. Do not reuse across environments.
All requests must use HTTPS (TLS 1.2 or higher).
You must allow outbound connections to the Meridian Base URLs.
IP whitelisting may be required for production access depending on your program configuration. Meridian provides details if applicable.

Every request must include the following headers:

Header	Description
`X-Meridian-Api-Key`	Issued by Meridian
`X-Meridian-Timestamp`	Current time in milliseconds (must be within 60 seconds of the request)
`X-Meridian-Signature`	HMAC SHA-256 signature

Meridian issues your API Key and Secret during Sandbox and production provisioning.

When Meridian receives the request, it validates the signature. If the signature does not match, the API immediately returns a 401 Unauthorized response.

Constructing the signature

Build the canonical string

Compute the signature as an HMAC SHA-256 hash over a canonical string that concatenates the following values in order:

Signature component	Notes
`API-Key`	Same value as `X-Meridian-Api-Key`
`Timestamp`	Same value as `X-Meridian-Timestamp`
`Request method`	Example: `GET`, `POST`, `PATCH`
`Request path`	Including any parameters. For example: `/v1/users/ususr-s8f9ds7f8sdf789d7fsd89f`
`Body contents`	The full stringified JSON contents of the request body. If there is no body, this can be an empty string.

Compute the HMAC

Compute the HMAC using the language-appropriate crypto library with the secret key.

Make sure you compute the HMAC with the API Secret that Meridian issued to you.

Compute the SHA-256 hash

Hash the final value using the SHA-256 algorithm and set it as the X-Meridian-Signature header.

import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

fun buildMeridianSignature(apiKey: String, apiSecret: String, method: String, path: String, body: String = ""): Map<String, String> {
    val timestamp = System.currentTimeMillis().toString()
    val canonical = apiKey + timestamp + method + path + body
    val mac = Mac.getInstance("HmacSHA256").apply {
        init(SecretKeySpec(apiSecret.toByteArray(), "HmacSHA256"))
    }
    val signature = mac.doFinal(canonical.toByteArray())
        .joinToString("") { "%02x".format(it) }

    return mapOf(
        "X-Meridian-Api-Key" to apiKey,
        "X-Meridian-Timestamp" to timestamp,
        "X-Meridian-Signature" to signature,
        "Content-Type" to "application/json"
    )
}

import CryptoKit
import Foundation

func buildMeridianSignature(apiKey: String, apiSecret: String, method: String, path: String, body: String = "") -> [String: String] {
    let timestamp = String(Int(Date().timeIntervalSince1970 * 1000))
    let canonical = apiKey + timestamp + method + path + body
    let key = SymmetricKey(data: Data(apiSecret.utf8))
    let signature = HMAC<SHA256>.authenticationCode(for: Data(canonical.utf8), using: key)
        .map { String(format: "%02x", $0) }.joined()

    return [
        "X-Meridian-Api-Key": apiKey,
        "X-Meridian-Timestamp": timestamp,
        "X-Meridian-Signature": signature,
        "Content-Type": "application/json"
    ]
}

// ─── Config ──────────────────────────────────────────────────────────────────
// Set these as collection variables (never hardcode secrets)
const apiKey    = pm.variables.get("meridianApiKey");
const apiSecret = pm.variables.get("meridianApiSecret");

// ─── Timestamp (milliseconds) ─────────────────────────────────────────────────
const timestamp = Date.now().toString();

// ─── Request components ───────────────────────────────────────────────────────
const method = pm.request.method; // e.g. "POST"

const url = pm.request.url;
const qs  = url.getQueryString();
const path = url.getPath() + (qs ? "?" + qs : ""); // e.g. "/v1/virtual-accounts/sessions"

const body = pm.request.body?.raw ?? "";

// ─── Canonical string ─────────────────────────────────────────────────────────
const canonical = apiKey + timestamp + method + path + body;

// ─── HMAC-SHA256 signature ────────────────────────────────────────────────────
const signature = CryptoJS.HmacSHA256(canonical, apiSecret).toString(CryptoJS.enc.Hex);

// ─── Inject into request headers ─────────────────────────────────────────────
pm.variables.set("meridianTimestamp", timestamp);
pm.variables.set("meridianSignature", signature);

// ─── Debug ────────────────────────────────────────────────────────────────────
console.log("Timestamp :", timestamp);
console.log("Canonical :", canonical);
console.log("Signature :", signature);

Common errors

Meridian returns 401 Unauthorized for requests with missing or invalid signatures.

The most common causes are:

Canonical string fields concatenated in the wrong order.
Timestamp too far from the server’s current time.
Forgetting to compute the HMAC with your unique API Secret.
Forgetting to SHA-256 hash the final string.

​Constructing the signature

​Common errors

Constructing the signature

Common errors