Authentication

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

Required headers

Header	Value
`X-Esim-Story-Access-Key`	Your partner access key
`X-Esim-Story-Signature`	The signature built below, hex-encoded, lowercase
`X-Esim-Story-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}

Serialise your payload to a string. Keep that exact string — you will both hash it and send it.
Hash it with SHA-256 and hex-encode the digest, lowercase. That is BODY_SHA256.
Build the five-line string above.
Base64-decode your secret key.
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.

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-Esim-Story-Signature`	`X-Esim-Story-Webhook-Signature`

Either can be replaced without affecting the other. This page covers the first column; the second is covered under Verifying the signature.

Examples

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

#!/bin/bash

# Configuration
ACCESS_KEY="your_access_key"
SECRET_KEY="your_base64_encoded_secret_key"

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

# Request details
METHOD="POST"
PATH="/api/v1/api_partner/orders"

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

# Construct raw string
RAW_STRING="${METHOD}\n${PATH}\n${TIMESTAMP}\n${ACCESS_KEY}\n${BODY_SHA256}"

# Decode secret key and generate signature
DECODED_SECRET=$(echo -n "$SECRET_KEY" | base64 -d)
SIGNATURE=$(echo -n -e "$RAW_STRING" | openssl dgst -sha256 -hmac "$DECODED_SECRET" | cut -d' ' -f2)

# Make request
curl -X POST https://api.esimstory.com/api/v1/api_partner/orders \
  -H "Content-Type: application/json" \
  -H "X-Esim-Story-Access-Key: ${ACCESS_KEY}" \
  -H "X-Esim-Story-Signature: ${SIGNATURE}" \
  -H "X-Esim-Story-Timestamp: ${TIMESTAMP}" \
  -d "$BODY"

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

  // Construct raw string with newlines
  const rawString = `${method}\n${path}\n${timestamp}\n${accessKey}\n${bodySha256}`;

  // Decode Base64 secret key
  const decodedSecret = Buffer.from(secretKey, "base64");

  // Generate HMAC-SHA256 signature
  const signature = crypto
    .createHmac("sha256", decodedSecret)
    .update(rawString)
    .digest("hex");

  return signature;
}

// Generate timestamp (Unix seconds)
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: "1234567890",
  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.esimstory.com/api/v1/api_partner/orders",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Esim-Story-Access-Key": accessKey,
      "X-Esim-Story-Signature": signature,
      "X-Esim-Story-Timestamp": timestamp,
    },
    body,
  },
);

import hmac
import hashlib
import base64
import json
import time

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()

    # Construct raw string with newlines
    raw_string = f'{method}\n{path}\n{timestamp}\n{access_key}\n{body_sha256}'

    # Decode Base64 secret key
    decoded_secret = base64.b64decode(secret_key)

    # Generate HMAC-SHA256 signature
    signature = hmac.new(
        decoded_secret,
        raw_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return signature

# Generate timestamp (Unix seconds)
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': '1234567890',
    'products': [
        {'option_id': 'A1B2C3D4-E5F6-7890-ABCD-EF1234567890', 'qty': 1}
    ]
})

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

headers = {
    'Content-Type': 'application/json',
    'X-Esim-Story-Access-Key': access_key,
    'X-Esim-Story-Signature': signature,
    'X-Esim-Story-Timestamp': timestamp
}

# Send `body` itself — requests' json= would re-serialise and break the signature
response = requests.post(
    'https://api.esimstory.com' + path,
    headers=headers,
    data=body
)

require 'openssl'
require 'base64'
require 'json'
require 'time'

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)

  # Construct raw string with newlines
  raw_string = "#{method}\n#{path}\n#{timestamp}\n#{access_key}\n#{body_sha256}"

  # Decode Base64 secret key
  decoded_secret = Base64.decode64(secret_key)

  # Generate HMAC-SHA256 signature
  OpenSSL::HMAC.hexdigest('SHA256', decoded_secret, raw_string)
end

# Generate timestamp (Unix seconds)
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: '1234567890',
  products: [
    { option_id: 'A1B2C3D4-E5F6-7890-ABCD-EF1234567890', qty: 1 }
  ]
}.to_json

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

headers = {
  'Content-Type' => 'application/json',
  'X-Esim-Story-Access-Key' => access_key,
  'X-Esim-Story-Signature' => signature,
  'X-Esim-Story-Timestamp' => timestamp
}

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":"1234567890","products":[{"option_id":"A1B2C3D4-E5F6-7890-ABCD-EF1234567890","qty":1}]}

body SHA256 : 9539c713900e8827b8c7e4eeea9c093438d34ba45277753db795029eba5b7295
signature   : 4c843ca7b8d8f39f1a3ef5915ff28ca60e0a9183dd28d888fe9c2ac01733a87b

What we check

On every request, in this order:

All three headers are present.
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.
We rebuild the signature from your secret key and compare it in constant time.

Errors

Authentication failures return 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid signature."
  }
}

Error Messages:

"Missing required authentication headers." - One or more required headers (X-Esim-Story-Access-Key, X-Esim-Story-Signature, X-Esim-Story-Timestamp) are missing
"Request timestamp is too old or invalid." - Timestamp is outside the allowed time window or invalid format
"Invalid or missing access key. Please provide a valid X-Esim-Story-Access-Key header." - Access key is incorrect or partner not found
"Missing secret key in partner record." - Partner exists but has no secret key configured
"Invalid signature." - Signature verification failed. 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. Raw string built wrong — wrong line order, a literal \n instead of a newline, or the /api prefix missing from the path
3. Secret key not Base64-decoded before use
4. Body omitted from the raw string entirely (the digest line is required even when the body is empty)

Get Started

Endpoints

Required headers

Building the signature

Rules that trip people up

Two secrets, two conventions

Examples

Test vector

What we check

Errors

​Required headers

​Building the signature

​Rules that trip people up

​Two secrets, two conventions

​Examples

​Test vector

​What we check

​Errors

Required headers

Building the signature

Rules that trip people up

Two secrets, two conventions

Examples

Test vector

What we check

Errors