Skip to main content
  • 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:
HeaderDescription
X-Meridian-Api-KeyIssued by Meridian
X-Meridian-TimestampCurrent time in milliseconds (must be within 60 seconds of the request)
X-Meridian-SignatureHMAC 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

1

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 componentNotes
API-KeySame value as X-Meridian-Api-Key
TimestampSame value as X-Meridian-Timestamp
Request methodExample: GET, POST, PATCH
Request pathIncluding any parameters. For example:
/v1/users/ususr-s8f9ds7f8sdf789d7fsd89f
Body contentsThe full stringified JSON contents of the request body.
If there is no body, this can be an empty string.
2

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

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"
    )
}

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