Sessions

Create sessions from your backend. For the complete request and iframe example, follow the integration guide.


POST /session
Content-Type: application/json
x-operator-secret: YOUR_WEBHOOK_SECRET

Request fields

Field	Type	Required	Meaning
`clientId`	string	Yes	The client ID from onboarding.
`userId`	string	Yes	The logged-in player’s ID in your system.
`currency`	object	Yes	`{ "code": "ZAR" }` — the player’s currency. See below.
`token`	string	No	Your session reference, up to 512 characters. See below.
`limits`	object	No	Stake and exposure limits for this session, in its currency. See below.
`game`	string	No	Binds the session to one game, such as `"dice"`. Calls to any other game are refused. An unknown game is refused with `400` (`Unknown game: <game>`).

The session’s currency

Send currency with its code: an ISO 4217 code such as ZAR, EUR or USD, a crypto code such as BTC or mBTC, or a code agreed with us such as SC. The game plays in that currency and every amount on the wallet webhook is in it; Maktub converts nothing on the wire. Bets (including free-bet placements) and credits of a non-USD session may also carry usdRate, the USD value of one unit of the currency looked up for that operation. It is reporting metadata, not a conversion to apply to the wallet amount.

Field in `currency`	Type	Meaning
`code`	string	Required. The wire currency, echoed on every webhook. A code registered for your account is sent exactly as registered; a code we price globally is sent in our spelling (`zar` → `ZAR`, `mbtc` → `mBTC`).
`decimals`	integer, 0–10	Optional. How many decimals your wallet settles in this currency. A stake with more decimals is refused with `400`. Every payout is rounded half-down to this many decimals before it is sent. Without it, amounts keep up to ten decimals, as today.
`usdRate`	number	Optional. Your USD value of one unit. It is only compared with ours, to flag a difference; it is never used for conversion, limits or billing.

Maktub values every currency itself. The value comes from our fiat FX feed, from our crypto feed (BTC, ETH, LTC, BCH, DOGE, XRP, TRX, SOL, BNB, ADA, TON, USDT, USDC, DAI, POL, AVAX, DOT, LINK, XLM, EOS, plus the sub-units mBTC, uBTC, mETH, uETH, mLTC, uLTC), or, for a currency of your own such as a social coin, from the value and classification registered with us for your account before go-live. A currency is promotional (non-billable) when it cannot be redeemed for money or prizes. A session in a currency we have no value for is refused with 400 and the message Unsupported currency: <code>.

Session limits

limits narrows the limits configured for your account; it can never widen them. Amounts are in the session’s currency.

Field in `limits`	Type	Meaning
`minBet`	number	Smallest stake accepted.
`maxBet`	number	Largest stake accepted.
`maxExposure`	number	Largest payout, stake included, one round may produce. It works like your account’s `maxExposure`, and the smaller of the two applies: a single-shot win above the cap pays exactly the cap, Blackjack, Video Poker, Baccarat, Roulette, Double and Hilo lower their maximum stake to the cap divided by their maximum return, and a progressive round refuses a step that could pass it. With `currency.decimals` below 2 the cap is rounded down to those decimals. Omit it for no cap.

minBet must not exceed maxBet. Free bets are checked against minBet and maxBet when the player plays them, and against currency.decimals: a free bet outside that range, or with a finer stake, is not offered in the session and stays unused.

For language, theme, logos and display settings, use the optional appearance fields. Those fields belong in this same request.

Your session reference

There are two different values named token:

Where it appears	Who creates it	What it does
Optional `token` in your request	You	Correlates webhooks with a session in your system.
`token` in the response	Maktub	Authorizes the player to use the game.

If you send "token": "your-session-reference", wallet calls for that session include "sessionToken": "your-session-reference", starting with the initial balance check. The alias sessionToken is also accepted in the request; use token consistently and do not send both.

A later settlement without a new reference recovers the stored round’s value. If neither the current session nor the stored round has one, the field is absent. This reference is metadata; authenticate wallet calls using the webhook credentials.

Response

Success returns HTTP 200:

Field	Type	Meaning
`token`	string	Maktub’s player credential. Default lifetime: 24 hours.
`gameUrl`	string	Play base URL with the token and presentation parameters. It does not yet contain a game path.
`sessionUser`	object	Additional server data; not needed by the iframe.

Treat the token and launch URL as player credentials. To renew an expired session, call this endpoint again for the authenticated player and reload the iframe with the new launch URL.

Errors

Error responses contain message when supplied by the handler.

HTTP status	Check
`400`	The client ID, request fields (an unsupported `currency`, `limits.minBet` above `limits.maxBet`, an unknown `game`) and your webhook’s balance response.
`401`	The `x-operator-secret` header.
`429`	Slow down session creation before retrying.

User not recognized by operator. means the initial balance check failed or did not return a valid balance. Check the wallet endpoint before retrying the launch.