> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esimmu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

Every request is signed with HMAC-SHA256. Three headers carry the proof.

## Required headers

| Header | Value |
| - | - |
| `X-Esimmu-Access-Key` | Your partner access key |
| `X-Esimmu-Signature` | The signature built below, hex-encoded, lowercase |
| `X-Esimmu-Timestamp` | Unix seconds (UTC), within 5 minutes of our clock |

## Building the signature

Sign a string of five lines joined by newlines:

```
{HTTP_METHOD}\n{REQUEST_PATH}\n{TIMESTAMP}\n{ACCESS_KEY}\n{BODY_SHA256}
```

1. Serialise your payload to a string. Keep that exact string: you will both
   hash it and send it.
2. Hash it with SHA-256 and hex-encode the digest, lowercase. That is
   `BODY_SHA256`.
3. Build the five-line string above.
4. Base64-decode your secret key.
5. HMAC-SHA256 the five-line string with the decoded secret, and hex-encode the
   result, lowercase.

## Rules that trip people up

* **Method** uppercase and exact: `POST`, `GET`.
* **Path** exact and complete: `/api/v1/api_partner/orders`. Include the `/api`
  prefix; exclude the domain, the protocol, and any query string.
* **Timestamp** in seconds, not milliseconds, and within 5 minutes of our clock
  in either direction.
* **Newlines** must be real newline characters, not the two literal characters
  `\` and `n`.
* **Secret key** is Base64 and must be decoded before use, unlike the webhook
  signing secret, which is not. See [Two secrets, two
  conventions](#two-secrets-two-conventions).

> [!WARNING]
>
> `BODY_SHA256` must be the hash of the **exact bytes you send**. Serialise your
> payload to a string once, hash that string, and send that same string. Do not
> re-serialise the object for the request: a different key order, or added
> whitespace, produces a different hash and the request is rejected with
> `Invalid signature.`

For a request with no body, hash the empty string. There is no shorter format:
the raw string always has five lines. The digest of the empty string is a
constant:

```
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

## Two secrets, two conventions

You are issued two signing secrets. They point in opposite directions and are
used differently, and mixing them up produces a signature that never matches,
with nothing in the error to say why.

| | Secret key | Webhook signing secret |
| - | - | - |
| Signs | Requests **you send us** | Webhooks **we send you** |
| Encoding | Base64, **decode before use** | Plain string, **use verbatim** |
| Signed string | Five lines: method, path, timestamp, access key, body hash | `{timestamp}.{raw_body}` |
| Header | `X-Esimmu-Signature` | `X-Esimmu-Webhook-Signature` |

This page covers the first column; the second is covered under [Verifying the
signature](https://docs.esimmu.com/endpoints/webhooks.md#verifying-the-signature).

## Examples

All four use the same request body. Substitute the fixed credentials and
timestamp from the [test vector](#test-vector) and any of them will produce the
signature shown there.

```bash cURL theme={null}
#!/bin/bash

ACCESS_KEY="your_access_key"
SECRET_KEY="your_base64_encoded_secret_key"

# Unix seconds
TIMESTAMP=$(date +%s)

METHOD="POST"
PATH="/api/v1/api_partner/orders"

# Build the body once, then hash and send that exact string
BODY='{"external_order_id":"ORD-1001","products":[{"option_id":"A1B2C3D4-E5F6-7890-ABCD-EF1234567890","qty":1}]}'
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 | cut -d' ' -f2)

RAW_STRING="${METHOD}\n${PATH}\n${TIMESTAMP}\n${ACCESS_KEY}\n${BODY_SHA256}"

DECODED_SECRET=$(echo -n "$SECRET_KEY" | base64 -d)
SIGNATURE=$(echo -n -e "$RAW_STRING" | openssl dgst -sha256 -hmac "$DECODED_SECRET" | cut -d' ' -f2)

curl -X POST https://api.esimmu.com/api/v1/api_partner/orders \
  -H "Content-Type: application/json" \
  -H "X-Esimmu-Access-Key: ${ACCESS_KEY}" \
  -H "X-Esimmu-Signature: ${SIGNATURE}" \
  -H "X-Esimmu-Timestamp: ${TIMESTAMP}" \
  -d "$BODY"
```

```javascript JavaScript theme={null}
const crypto = require("crypto");

function generateSignature(method, path, timestamp, accessKey, secretKey, body) {
  // Hash the exact body string that will be sent
  const bodySha256 = crypto.createHash("sha256").update(body).digest("hex");

  const rawString = `${method}\n${path}\n${timestamp}\n${accessKey}\n${bodySha256}`;

  // The secret key is Base64: decode it first
  const decodedSecret = Buffer.from(secretKey, "base64");

  return crypto.createHmac("sha256", decodedSecret).update(rawString).digest("hex");
}

const timestamp = Math.floor(Date.now() / 1000).toString();
const method = "POST";
const path = "/api/v1/api_partner/orders";

// Serialise once: sign this string and send this same string
const body = JSON.stringify({
  external_order_id: "ORD-1001",
  products: [{ option_id: "A1B2C3D4-E5F6-7890-ABCD-EF1234567890", qty: 1 }],
});

const signature = generateSignature(method, path, timestamp, accessKey, secretKey, body);

const response = await fetch("https://api.esimmu.com/api/v1/api_partner/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Esimmu-Access-Key": accessKey,
    "X-Esimmu-Signature": signature,
    "X-Esimmu-Timestamp": timestamp,
  },
  body,
});
```

```python Python theme={null}
import base64
import hashlib
import hmac
import json
import time

import requests

def generate_signature(method, path, timestamp, access_key, secret_key, body):
    # Hash the exact body string that will be sent
    body_sha256 = hashlib.sha256(body.encode("utf-8")).hexdigest()

    raw_string = f"{method}\n{path}\n{timestamp}\n{access_key}\n{body_sha256}"

    # The secret key is Base64: decode it first
    decoded_secret = base64.b64decode(secret_key)

    return hmac.new(decoded_secret, raw_string.encode("utf-8"), hashlib.sha256).hexdigest()

timestamp = str(int(time.time()))
method = "POST"
path = "/api/v1/api_partner/orders"

# Serialise once: sign this string and send this same string
body = json.dumps({
    "external_order_id": "ORD-1001",
    "products": [{"option_id": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890", "qty": 1}],
})

signature = generate_signature(method, path, timestamp, access_key, secret_key, body)

# Send `body` itself: requests' json= would re-serialise and break the signature
response = requests.post(
    "https://api.esimmu.com" + path,
    headers={
        "Content-Type": "application/json",
        "X-Esimmu-Access-Key": access_key,
        "X-Esimmu-Signature": signature,
        "X-Esimmu-Timestamp": timestamp,
    },
    data=body,
)
```

```ruby Ruby theme={null}
require "base64"
require "json"
require "net/http"
require "openssl"

def generate_signature(method, path, timestamp, access_key, secret_key, body)
  # Hash the exact body string that will be sent
  body_sha256 = OpenSSL::Digest::SHA256.hexdigest(body)

  raw_string = "#{method}\n#{path}\n#{timestamp}\n#{access_key}\n#{body_sha256}"

  # The secret key is Base64: decode it first
  OpenSSL::HMAC.hexdigest("SHA256", Base64.decode64(secret_key), raw_string)
end

timestamp = Time.now.to_i.to_s
method = "POST"
path = "/api/v1/api_partner/orders"

# Serialise once: sign this string and send this same string
body = {
  external_order_id: "ORD-1001",
  products: [{ option_id: "A1B2C3D4-E5F6-7890-ABCD-EF1234567890", qty: 1 }]
}.to_json

signature = generate_signature(method, path, timestamp, access_key, secret_key, body)

uri = URI("https://api.esimmu.com#{path}")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-Esimmu-Access-Key"] = access_key
request["X-Esimmu-Signature"] = signature
request["X-Esimmu-Timestamp"] = timestamp
request.body = body

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
```

## Test vector

Fixed values to check your implementation against. Useful before you have
credentials, and for confirming a change to your signing code did not alter the
result.

```
access_key : test_access_key
secret_key : dGVzdF9zZWNyZXRfa2V5      (Base64; decodes to test_secret_key)
timestamp  : 1754400000
method     : POST
path       : /api/v1/api_partner/orders
body       : {"external_order_id":"ORD-1001","products":[{"option_id":"A1B2C3D4-E5F6-7890-ABCD-EF1234567890","qty":1}]}

body SHA256 : 71cb5b302214ee4c47f68dbe7cdb2ab0187a118bb1324a2c8985b51f1a52081f
signature   : c17d27bfca42d4165fefb3d16f33824210e56d8c52ab44f68754be748cac4d6d
```

## What we check

On every request, in this order:

1. All three headers are present.
2. The timestamp is within 5 minutes of our clock. Generate it fresh per
   request and keep your server on NTP: clock drift is the usual cause of
   `Request timestamp is too old or invalid.`
3. We rebuild the signature from your secret key and compare it in constant
   time.

## Errors

Authentication failures return `401 Unauthorized`:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid signature."
  }
}
```

| Message | Cause |
| - | - |
| `Missing required authentication headers.` | One or more of the three headers is missing |
| `Request timestamp is too old or invalid.` | Timestamp outside the 5-minute window, or not Unix seconds |
| `Invalid or missing access key. Please provide a valid X-Esimmu-Access-Key header.` | Access key unknown |
| `Missing secret key in esimmu partner record.` | Your account has no secret key yet; ask your account manager |
| `Invalid signature.` | Signature verification failed. See below |

`Invalid signature.`, in order of likelihood:

1. **The body sent differs from the body hashed.** Re-serialising the payload
   for the request produces different bytes than the string you hashed.
   Serialise once, hash that string, send that string.
2. The raw string is built wrong: wrong line order, a literal `\n` instead of a
   newline, or the `/api` prefix missing from the path.
3. The secret key was not Base64-decoded before use.
4. The body hash line is missing. It is required even when the body is empty.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.