Create session
POST
/v1/sessions
Open a game for one of your players and get the URL to open it at.
SignedSandboxProduction
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| player_id | string | yes | Your reference, up to 120 characters. No player is created; it is what our wallet callbacks will name.Example: p-1 |
| currency | string | yes | ISO 4217, 3 to 10 characters. Fixed for the session.Example: EUR |
| game_id | string | yes | The catalogue id from GET /v1/games.Example: 6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10 |
| locale | string | no | en, ru-RU… translated to what the provider serves. At most 20 characters. |
| lobby_url | string | no | Where the game's "back to lobby" goes. At most 500 characters. |
| ttl_minutes | integer | no | 1..1440, default 240 (four hours). The launch is a bearer credential for a balance: keep it short. |
| player_country | string | no | ISO 3166-1 alpha-2, what you know of the player. Used only where the address says nothing. |
| player_ip | string | no | Send it. The player's own address, up to 45 characters; the country is read off it, and the game providers' country rules go by that.Example: 203.0.113.9 |
| player_device | string | no | desktop or mobile. |
| deposit_url | string | no | Up to 500 characters. Where a provider that supports it sends a player who ran out of money. |
| player_name | string | no | Up to 32 characters. The nickname other players see in multiplayer games (Callisto Minis tables and match feeds); other games ignore it. Never the player's real name. Absent, the game shows its own pseudonym; a changed nickname applies from the next session.Example: Ace_77 |
| brand | object | no | Which of your brands the player plays on, if you run more than one. Some game providers keep a separate account per brand; the game then opens under that brand's account, and a brand without one opens under yours. Absent, the session is yours as a whole, as before. |
| brand.code | string | no | Required when brand is sent. Your own code for the brand, 1 to 64 letters, digits, . _ -, starting with a letter or digit. Keep it stable: the per-brand accounts are set up under it.Example: brand-a |
| brand.domain | string | no | The brand's site as a bare host name, up to 253 characters, with no scheme, port or path. Kept with the session for reporting.Example: casino.example |
Request
{
"player_id": "p-1",
"currency": "EUR",
"game_id": "6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10",
"locale": "en",
"lobby_url": "https://casino.example/lobby",
"player_ip": "203.0.113.9",
"player_device": "mobile",
"brand": { "code": "brand-a", "domain": "casino.example" }
}Response 200
{
"session_id": "2222aaaa-5b6c-4d7e-8f90-a1b2c3d4e5f6",
"launch_url": "https://provider…/play?token=…",
"expires_at": "2026-09-29T16:00:00Z"
}Open the game at launch_url
Do not build a launch URL from a host and a game id. Providers move their launch hosts without notice, and a URL built from a list breaks the same day while looking like a broken game.Possible errors
| error | HTTP | Retry | Meaning |
|---|---|---|---|
| VALIDATION_FAILED | 422 | no | A field is missing, out of range or of the wrong JSON type, or the body is not valid JSON. Also an unknown type, or a cursor that did not come from this listing, on GET /v1/games. Every broken field is listed in fields with the rule it broke; "body" when the JSON does not parse. Also a request the service behind the call refused for a reason of its own: then fields is empty and message says why. |
| GAME_UNAVAILABLE | 409 | no | The game is not in your window, whether or not it exists. |
| GAME_RESTRICTED_IN_COUNTRY | 409 | no | The game cannot be played in the player's country. |
| PLAYER_BLOCKED | 409 | no | The aggregator has stopped this player. No session opens until the block is lifted. |
| UPSTREAM_UNAVAILABLE | 503 | yes | A service behind the API did not answer in time or answered with an error (HTTP 503), or something failed on our side (HTTP 500). The outcome is unknown. Also when your key cannot be checked because the service that holds keys is unavailable, and when the game providers refused to open the game for the moment: no session is left open then. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
Notes
A repeated POST /v1/sessions opens another session: it is not idempotent, and one left unanswered is safe to send again, since an unused session simply expires. When every provider of the game refuses the launch for the moment, the answer is UPSTREAM_UNAVAILABLE with retryable: true and no session is left open, so a repeat is safe too. session_id and the token inside launch_url are different values: the token is a bearer credential, the id is what you may quote. Store session_id with the catalogue game_id you launched; wallet callbacks carry it.
