JRGS Casino API

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:

HeaderValue
X-Key-Idwhich key signed the request
X-TimestampUnix time in seconds, as a decimal string
X-Signaturethe 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: POST or GET.
  • 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=50 and /catalog/games?limit=50&market=gb are 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 GET has an empty body, whose hash is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

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
794a757eeb89a89812fd44301386d166486288b6b4c3f0630c4a6eda6b2c0c36

Signature:

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

sign-launch.mjs
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:

  1. The body is read, at most 1 MiB. A larger or unreadable body is a 400 with ERR_VAL, reason body.
  2. X-Timestamp must be an integer within 60 seconds of the RGS clock.
  3. 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.
  4. The key must carry the scope of the route: launch for the two session routes, catalog for the catalog, free_rounds for the free rounds routes.
  5. 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.reasonWhat to check
timestampthe header is missing or not an integer, or your clock is more than 60 s off
signaturethe 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
scopethe key was registered without the route's scope
addressyour 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): notBefore and notAfter; 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

  1. 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.
  2. Wait until the backoffice shows Live. From then both keys work.
  3. 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.
  4. When the window ends, the old key is refused: a request signed with it gets 401 with ERR_ATE and reason signature, 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):

ee6d032aa21850b86982a30687829d4d9dcc66750b729493802a0bd6f72a6cdc

Response body {"status":"ok","balance":9000000,"operatorTxId":"tx-1","alreadyProcessed":false} with status 200, same path and timestamp:

291f744f8be52f8552c10feeac40b488d2af15663a5a269d33cc5d25764ec025

Code

wallet-sign.mjs
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:

wallet-server.mjs
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:

  1. 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.
  2. 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.
  3. 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.

On this page