Authentication and signing
Ed25519 signatures on the launch requests you send, and HMAC-SHA256 signatures on wallet calls in both directions, with working code.
There are no sessions, bearer tokens or API key headers. Every request is signed, in both directions. Requests carry
all three headers below; wallet responses carry X-Timestamp and X-Signature:
| Header | Value |
|---|---|
X-Key-Id | which key signed the request |
X-Timestamp | Unix time in seconds, as a decimal string |
X-Signature | the signature (base64 for launch requests, hex for wallet calls) |
A timestamp more than 60 seconds from the receiver's clock, either way, is refused. Keep your clocks on NTP.
Launch requests: Ed25519
Every call you make to the launch API (POST /sessions, POST /sessions/{id}/launch-url, GET /catalog/games) is
signed with your Ed25519 private key.
The string to sign
Four lines joined by a single \n, with no trailing newline:
<X-Timestamp>
<METHOD>
<path?query>
<hex sha256 of the body>- METHOD is the HTTP method in upper case, as sent:
POSTorGET. - path?query is the request target exactly as it goes on the wire: the path, and when there is a query,
?and the query in the same order and with the same escaping./catalog/games?market=gb&limit=50and/catalog/games?limit=50&market=gbare different strings; sign the one you send. - hex sha256 of the body is the lower-case hex SHA-256 of the exact body bytes. A
GEThas an empty body, whose hash ise3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
Sign those bytes with Ed25519 and send the 64-byte signature as standard base64, with padding, in X-Signature.
Sign the bytes you send
Serialise the JSON body once, sign that string, and send that same string. Serialising twice can reorder keys or change spacing, and the hash no longer matches.
Worked example
This uses the RFC 8032 test key. It is public: never use it for anything real.
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ1hsZ3v/VpguoRK9JLsLMREScVpezJpGXA7rAMcrn9g
-----END PRIVATE KEY-----Its public key, as you would register it: 11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=. Key id casino-2026-11,
timestamp 1793750400, and this body (148 bytes, no trailing newline):
{"requestId":"launch-7f3a","marketId":"gb","gameId":"slots","player":{"id":"p-1001","country":"GB","currency":"GBP"},"lang":"en","device":"desktop"}String to sign for POST /sessions:
1793750400
POST
/sessions
794a757eeb89a89812fd44301386d166486288b6b4c3f0630c4a6eda6b2c0c36Signature:
qlYETLpJSl9g2LRaApegbWH7LzuxI70GO4Uyu+EJ6zAnMQ9YCQHZ3cijyWv6tkpnERH0af3PVvKqH1AuzvpFCg==And for GET /catalog/games?market=gb&limit=50 with the same key and timestamp (empty body):
ERfw80FcEImLSVeqPxiKSzmGflrNvYUnC4mr6JSoA/CurLA80CNcdgfgjtJiPqPSq74ODh5Vl3ptXFpRTU1GAA==Ed25519 signatures are deterministic, so your code must produce exactly these values from these inputs.
Code
import { createHash, createPrivateKey, sign } from 'node:crypto';
import { readFileSync } from 'node:fs';
const KEY_ID = 'casino-2026-11';
const privateKey = createPrivateKey(readFileSync('launch-key.pem'));
// body is the exact bytes you send: a string or a Buffer, '' for a GET.
export function signLaunch(method, pathQuery, body, timestamp) {
timestamp ??= String(Math.floor(Date.now() / 1000));
const bodyHash = createHash('sha256').update(body).digest('hex');
const payload = `${timestamp}\n${method}\n${pathQuery}\n${bodyHash}`;
const signature = sign(null, Buffer.from(payload), privateKey).toString('base64');
return { 'X-Key-Id': KEY_ID, 'X-Timestamp': timestamp, 'X-Signature': signature };
}import { signLaunch } from './sign-launch.mjs';
const body = JSON.stringify({ requestId: 'launch-7f3a', marketId: 'gb', gameId: 'slots',
player: { id: 'p-1001', country: 'GB', currency: 'GBP' }, lang: 'en', device: 'desktop' });
const res = await fetch('https://rgs.example.com/sessions', {
method: 'POST',
headers: { 'Content-Type': 'application/json', ...signLaunch('POST', '/sessions', body) },
body,
});When a request is refused
The RGS checks in this order, and the first failure answers:
- The body is read, at most 1 MiB. A larger or unreadable body is a
400withERR_VAL, reasonbody. X-Timestampmust be an integer within 60 seconds of the RGS clock.- The key must exist and be usable, and the signature must verify. An unknown key and a bad signature give the same answer, so key ids cannot be probed.
- The key must carry the scope of the route:
launchfor the two session routes,catalogfor the catalog,free_roundsfor the free rounds routes. - The request must come from one of the key's networks.
Steps 2 to 5 answer 401 with ERR_ATE, and details.reason names the check:
{
"error": "ERR_ATE",
"message": "request authentication failed",
"details": { "reason": "signature", "retryable": false },
"requestId": "fbfa2dba-7a2f-46d1-9793-818e1814912d"
}details.reason | What to check |
|---|---|
timestamp | the header is missing or not an integer, or your clock is more than 60 s off |
signature | the key id, the private key, or the string to sign (usually the query or the body bytes). Also a revoked key, a key outside its notBefore/notAfter window, or a suspended casino |
scope | the key was registered without the route's scope |
address | your request came from an address outside the key's CIDRs |
Retrying a 401 unchanged gives the same answer. The requestId in an error is your X-Request-Id header if you sent
one, otherwise one the RGS generated, so a 401 always carries one of those; quote it when you contact us. On
POST /sessions, once authentication has passed and the body parses with a non-empty requestId, errors carry the
body's requestId instead.
Keys and rotation
A launch key belongs to your casino. A key carries:
- key id: your choice, unique across the RGS; you send it in
X-Key-Id; - scopes: one or more of
launch,catalog,free_rounds; - allowed networks: at least one CIDR, for example
203.0.113.0/24; - validity window (optional):
notBeforeandnotAfter; outside it the key is refused.
You can add a key in two ways, both under Setup → Keys in the backoffice, by a user with key management rights:
- Register your public key (recommended): you keep the private key; you hand over only the base64 public key.
- Generate a key pair in the backoffice: the private key is shown once, as a PKCS#8 PEM file to download. We keep only the public half. Store the file before you close the dialog; it cannot be shown again.
A key is used when it is active, inside its validity window, and your casino is active. The backoffice shows Live once a change has reached the RGS, usually within seconds. There is no limit on how many keys work at once.
Rotating a launch key
- In Setup → Keys, press Rotate on the current key. Give the new key id, your new public key (or generate
one), and the overlap window: how long the old key keeps working, 1 hour to 30 days, 7 days by default. Rotation
never extends an old key's existing
notAfter; the window can only shorten it. - Wait until the backoffice shows Live. From then both keys work.
- Deploy the new key id and private key to every server that signs requests. The Last used column shows when each key last signed a request, so you can see the old one fall out of use.
- When the window ends, the old key is refused: a request signed with it gets
401withERR_ATEand reasonsignature, exactly as an unknown key. Nothing else changes.
Revoke ends a key at once, with no window: use it when a private key may have leaked, then add a new key. A revoked key cannot be reactivated.
Wallet calls: HMAC-SHA256
Every call the RGS makes to your wallet is a POST with a JSON body, signed with HMAC-SHA256 under a secret shared
between you and us. Your response must be signed too: the RGS does not believe an unsigned or wrongly signed success,
because a forged "ok" would count as money moved.
The secret is a string agreed at onboarding. The HMAC key is that string's UTF-8 bytes, used as they are (not
hex- or base64-decoded). X-Key-Id on our requests carries the key id registered with your wallet, so you can tell
secrets apart during a change.
The strings to sign
The request, which you verify:
<X-Timestamp>
POST
<path>
<hex sha256 of the request body>Your response, which you sign:
<X-Timestamp of your response>
<HTTP status code, e.g. 200>
<path>
<hex sha256 of the response body>Lines are joined by \n, without a trailing newline. The signature is the lower-case hex HMAC-SHA256, in
X-Signature. Your response carries its own X-Timestamp (your clock, Unix seconds), and the RGS refuses one more
than 60 seconds from its clock.
Which path is signed
The path is the full path of the URL the RGS calls, without query or host: your registered base URL's path followed
by the route. With the base URL https://wallet.casino.example/rgs, a debit is signed with /rgs/debit, not
/debit. Sign your response with the same path. If a proxy in front of your wallet strips or rewrites the prefix,
verify with the path the RGS called, not the one your application sees.
Only a 2xx response is checked for a signature. A 401 or 403 tells the RGS its own key or secret is wrong, and
that no money moved. Any other status is an unknown outcome (see Errors and money states), so give
every business answer, refusals included, as a signed 200 with "status": "error".
Worked example
Secret example-secret, base URL https://wallet.casino.example/rgs, timestamp 1793750400, request body:
{"transactionId":"r-1:debit:1","roundId":"r-1","playerId":"p-1001","gameId":"slots","gameVersion":"1.0.0","variant":"957","currency":"GBP","amount":1000000}Request signature (method POST, path /rgs/debit):
ee6d032aa21850b86982a30687829d4d9dcc66750b729493802a0bd6f72a6cdcResponse body {"status":"ok","balance":9000000,"operatorTxId":"tx-1","alreadyProcessed":false} with status 200,
same path and timestamp:
291f744f8be52f8552c10feeac40b488d2af15663a5a269d33cc5d25764ec025Code
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
const SECRET = Buffer.from(process.env.RGS_WALLET_SECRET, 'utf8');
const MAX_SKEW = 60;
function mac(timestamp, first, path, body) {
const bodyHash = createHash('sha256').update(body).digest('hex');
return createHmac('sha256', SECRET)
.update(`${timestamp}\n${first}\n${path}\n${bodyHash}`)
.digest('hex');
}
// path is the request's path as it reached you, e.g. /rgs/debit; body is the raw bytes.
export function verifyRequest(headers, method, path, body) {
const timestamp = headers['x-timestamp'] ?? '';
const now = Math.floor(Date.now() / 1000);
if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > MAX_SKEW) return false;
const want = Buffer.from(mac(timestamp, method, path, body));
const got = Buffer.from(headers['x-signature'] ?? '');
return got.length === want.length && timingSafeEqual(got, want);
}
// Sign the response with the same path the request was signed with.
export function signResponse(status, path, body) {
const timestamp = String(Math.floor(Date.now() / 1000));
return { 'X-Timestamp': timestamp, 'X-Signature': mac(timestamp, String(status), path, body) };
}A minimal server with node:http:
import { createServer } from 'node:http';
import { verifyRequest, signResponse } from './wallet-sign.mjs';
createServer((req, res) => {
const chunks = [];
req.on('data', (c) => chunks.push(c));
req.on('end', () => {
const raw = Buffer.concat(chunks);
const path = new URL(req.url, 'http://x').pathname;
if (!verifyRequest(req.headers, req.method, path, raw)) {
res.writeHead(401).end();
return;
}
const body = Buffer.from(JSON.stringify({ status: 'ok', balance: 9000000, operatorTxId: 'tx-1', alreadyProcessed: false }));
res.writeHead(200, { 'Content-Type': 'application/json', ...signResponse(200, path, body) });
res.end(body);
});
}).listen(8080);Verify against the raw body bytes, before any JSON parsing; a framework that parses the body for you must also give you the raw bytes.
Answer a request that fails verification with 401 and no money moved. Compare signatures in constant time, as
above.
Rotating the wallet secret
Wallet calls are signed with a secret we share. Rotation adds a second key id and secret that both sides hold for a while, so no call fails:
- Agree a new key id and secret with us. We add it to our wallet service; you start accepting both: pick the secret
by the request's
X-Key-Id, and sign your response with the secret that request used. - We switch the key id the RGS signs with (Setup → Keys → Rotate wallet key). Calls already on their way finish under the old key; every new call, retries included, carries the new key id.
- When we confirm that no call has used the old key id for a while, drop the old secret.
A 401 or 403 to a credit or rollback stops that round until the RGS operators retry it, so keep both secrets
until step 3.