Core concepts

HMAC signing

Payload canonicalization and replay protection.

Who must sign

Growth, Scale and Enterprise keys must also sign every request with HMAC-SHA256, sending X-RailCore-Timestamp, X-RailCore-Nonce and X-RailCore-Signature. Free and Starter keys send the key alone.

Required headers

HTTP
X-RailCore-Key: rk_live_...
X-RailCore-Timestamp: 1785472200
X-RailCore-Nonce: 01J5Z7Y8N2K4M6P8R0T2V4X6Z8
X-RailCore-Signature: base64_hmac_value

The signing secret is shown once, with the key, when you create or rotate a Growth, Scale or Enterprise key. It never leaves your server: it is not sent in any header.

The key header is your choice: the signature does not cover it, so it verifies the same in X-RailCore-Key, Authorization: Bearer or X-Api-Key.

Signature payload

Canonical bytes
METHOD
PATH
CANONICAL_QUERY
SHA256_HEX(BODY)
TIMESTAMP
NONCE

Signing rules

  • Encode with RFC 3986. Leave only A-Z, a-z, 0-9, hyphen, underscore, period, and tilde unescaped.
  • Use uppercase percent-encoding hex.
  • Sort keys in ASCII order. Sort repeated values and emit each pair.
  • Hash the exact bytes of the request body, as sent. Any JSON formatting works, compact or indented, as long as the bytes you hash are the bytes you send. A request with no body hashes zero bytes.
  • Acceptable timestamp skew is plus or minus 5 min. Generate a fresh 16 to 128 character nonce for every attempt.

Check a signature

Build the same request here and compare each line with what your code produces. A mismatch in the canonical query or the body hash is the usual cause of SIGNATURE_INVALID.

Stays in this page's memory. The signature is computed in your browser; nothing here is sent, stored or recorded.

Node.js signing core

Node.js
import crypto from "node:crypto";

const method = "GET";
const path = "/v1/routes/trains";
// A week from today, so the sample never asks about a date that has passed.
const date = new Date(Date.now() + 7 * 86_400_000).toISOString().slice(0, 10);
const query = `date=${date}&from=BSL&to=ADI`;
const bodyHash = crypto.createHash("sha256").update("").digest("hex");
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString("hex");
const payload = [method, path, query, bodyHash, timestamp, nonce].join("\n");
const signature = crypto
  .createHmac("sha256", process.env.RAILCORE_HMAC_SECRET)
  .update(payload)
  .digest("base64");

Signing a body

Serialize the body once, hash that string, and send the same string. The API hashes the bytes it receives, so whitespace and key order are yours to choose.

Node.js
// The exact string you send. Indented or compact, either signs correctly.
const body = JSON.stringify({ journeys: [{ from: "BSL", to: "ADI", date }] }, null, 2);
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const payload = ["POST", "/v1/journeys/compare", "", bodyHash, timestamp, nonce].join("\n");
// ...sign payload as above, then send the same string:
await fetch("https://ir.railcore.tech/v1/journeys/compare", {
  method: "POST",
  headers: { "Content-Type": "application/json", /* key and signature headers */ },
  body,
});

Do not sign in a frontend

The signing secret is a server credential. A leaked API key alone should not be enough to forge signed requests.

Common failures

Code, Check table
CodeCheck
SIGNATURE_INVALIDSecret, path including /v1, canonical query ordering, and that the body hash is of the exact bytes sent
TIMESTAMP_EXPIREDNTP and Unix seconds
NONCE_REUSEDGenerate a new nonce for every retry

Last updated