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.

The session’s currency

Send currency with the code only: an ISO 4217 code such as ZAR, EUR or USD, or a sweepstakes 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.

Maktub needs a USD exchange rate for the code: a session in a currency it has no rate for is refused with 400 and the message Unsupported currency: <code>. Send only code inside currency.

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 (including an unsupported `currency`) 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.