Core concepts
Payload canonicalization and replay protection.
Who must sign
X-RailCore-Key: rk_live_...
X-RailCore-Timestamp: 1785472200
X-RailCore-Nonce: 01J5Z7Y8N2K4M6P8R0T2V4X6Z8
X-RailCore-Signature: base64_hmac_valueThe 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.
METHOD
PATH
CANONICAL_QUERY
SHA256_HEX(BODY)
TIMESTAMP
NONCEBuild 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.
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");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.
// 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
| Code | Check |
|---|---|
| SIGNATURE_INVALID | Secret, path including /v1, canonical query ordering, and that the body hash is of the exact bytes sent |
| TIMESTAMP_EXPIRED | NTP and Unix seconds |
| NONCE_REUSED | Generate a new nonce for every retry |
Last updated