Skip to content
Player sessions / Create session
Player sessions

Create session

POST

/v1/sessions

Open a game for one of your players and get the URL to open it at.

SignedSandboxProduction

Request body

FieldTypeRequiredDescription
player_idstringyesYour reference, up to 120 characters. No player is created; it is what our wallet callbacks will name.Example: p-1
currencystringyesISO 4217, 3 to 10 characters. Fixed for the session.Example: EUR
game_idstringyesThe catalogue id from GET /v1/games.Example: 6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10
localestringnoen, ru-RU… translated to what the provider serves. At most 20 characters.
lobby_urlstringnoWhere the game's "back to lobby" goes. At most 500 characters.
ttl_minutesintegerno1..1440, default 240 (four hours). The launch is a bearer credential for a balance: keep it short.
player_countrystringnoISO 3166-1 alpha-2, what you know of the player. Used only where the address says nothing.
player_ipstringnoSend 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_devicestringnodesktop or mobile.
deposit_urlstringnoUp to 500 characters. Where a provider that supports it sends a player who ran out of money.
player_namestringnoUp 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
brandobjectnoWhich 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.codestringnoRequired 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.domainstringnoThe 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

errorHTTPRetryMeaning
VALIDATION_FAILED422noA 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_UNAVAILABLE409noThe game is not in your window, whether or not it exists.
GAME_RESTRICTED_IN_COUNTRY409noThe game cannot be played in the player's country.
PLAYER_BLOCKED409noThe aggregator has stopped this player. No session opens until the block is lifted.
UPSTREAM_UNAVAILABLE503yesA 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.