JRGS Casino API
ReferenceLaunch API

Start a game session

The casino calls POST /sessions on the launch API, with a key that holds the launch scope.

POST/sessions

Starts a session of one player in one game on one market and returns the URL that opens it. Validation, in this order: requestId, player.id and gameId are present; marketId is present; the market exists and belongs to the key's operator; the player's country and currency are the market's; the game is on the market.

Idempotency. requestId names one launch per operator. Repeating it with the same player.id, gameId, marketId and player.currency returns the same session with a fresh launch token; the earlier token stops working. A repeat is answered from the stored session right after the required fields are checked, before any market, country, game, certification, stake or release check: a change of configuration since the first call does not refuse it, and it gets the first call's version and variant. Apart from the four fields that must match, the repeat's values (mode, country, maxStake, lang, device, returnUrl) are not read: the session keeps the first call's. The same requestId with any of those four different, or for a session that has been opened or closed since, is refused with ERR_VAL request_id.

Open round. If the player has an unfinished round in this game, the session runs that round's game version, variant and math, so the round can be finished, and the market's wallet certification is not required. Otherwise the market's current version and variant are used, and a market whose wallet has no current conformance pass refuses with ERR_WALLET_NOT_CERTIFIED (internal and demo markets are exempt). ERR_MAINTENANCE applies either way: a release whose client or schema has not passed its check takes no new session, an open round's included.

One session at a time. A new session closes the player's previous session in the same game. On a market with one-game-at-a-time rules (UK RTS 14C) it closes the player's previous session in any game. With onOpenSession resume the previous session may be kept instead, see Open session.

Open session. onOpenSession says what to do with the player's open session in the game. new, the default, also when absent or empty, closes it and starts a new session, as described above. resume keeps it and gives it a new launch URL: the answer's sessionId is then the open session's and resumed is true. The session is resumed when it is open, has not been idle too long, and would be started with the same game version, variant, bet levels and limits as a new one: the same game, market, currency, mode and country, and the same version, variant, math, bet levels, default bet and stake limit as the market and the request give now. Otherwise resume starts a new session, as new does, and never refuses because there was nothing to resume. The session keeps its id and its start time. The launch URL the casino held before is revoked if it was not opened yet; a client already playing in the session keeps playing, and the new URL gives the same session when opened. A resume request's requestId is not stored: repeating it resumes again and gives a new URL. A requestId of an earlier launch is still answered as described in Idempotency, before any of this. Any other value is refused with ERR_VAL on_open_session.

Stakes. The session's stake limit is the smaller of the market's limit and player.maxStake; bet levels above it are dropped. If none is left, ERR_GLE stake_limit.

The launch URL is the game client's index page with a fragment: {index}#api={rgs}&device={device}&lang={lang}&lt={token} (form-encoded, keys in this order, lang and device present even when empty). Redirect the player to it as is. The launch token in lt is single use and expires 60 s after issue (launchExpiresAt); get a new one with POST /sessions/{id}/launch-url until the player opens the session.

Free rounds. When the player has an active free rounds award (POST /free-rounds) for the game on this market and in this currency, the session plays it first, and the answer's freeRounds names it. A repeat and a new launch URL answer the same way.

Header Parameters

X-Key-Id*string

The id of the signing key, as issued with it.

X-Timestamp*string

Unix seconds, within 60 s of the RGS clock. The first line of the signed payload.

Match^-?[0-9]+$
X-Signature*string

Base64 (standard, padded) Ed25519 signature of "{X-Timestamp}\n{METHOD}\n{path?query}\n{hex(sha256(body))}".

Formatbyte
X-Request-Id?string

Echoed as requestId in an error. One is generated when absent. On POST /sessions the body's requestId replaces it once the body has been read and signed.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Unknown fields are ignored.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/sessions" \  -H "X-Key-Id: string" \  -H "X-Timestamp: 1793707200" \  -H "X-Signature: string" \  -H "Content-Type: application/json" \  -d '{    "requestId": "7c0e9b54-2f0a-4a8e-9a63-0d4b1e6f2a10",    "marketId": "gb",    "gameId": "slots",    "mode": "real",    "player": {      "id": "p-1001",      "country": "GB",      "currency": "GBP",      "maxStake": 2000000    },    "lang": "en",    "device": "desktop",    "returnUrl": "https://casino.example/lobby"  }'
{  "sessionId": "019a4b5e-6f70-7c3d-8e9f-0a1b2c3d4e5f",  "launchUrl": "https://cdn.example.com/slots/1.0.0/index.html#api=https%3A%2F%2Fapi.example.com&device=desktop&lang=en&lt=ZXhhbXBsZS1sYXVuY2gtdG9rZW4tbm90LXJlYWwtMDA",  "launchExpiresAt": "2026-11-03T12:01:00Z",  "gameVersion": "1.0.0",  "variant": "957"}