Operators

Launch a game

Create a session for a player and receive the URL that opens the game.

http

POST /games/request-access
Authorization: Bearer <access-token>
Content-Type: application/json

Request

Field	Type	Required	Description
`user_id`	string	Yes	Your player ID. KOI echoes it as `user_id` in every callback.
`username`	string	Yes	Display name shown in the game.
`game`	string	Yes	Game `slug` from List games.
`currency`	string	No	ISO 4217 code, for example `BRL`. Default `brl`. Echoed in callbacks as sent.
`lang`	string	No	Interface language: `pt-BR`, `en-US`, `es-ES`, `ru-RU` or `zh-CN`. Default `pt`. Coverage varies by game.
`balance`	number	No	Player balance to display at launch. Your wallet remains the source of truth.
`avatar_url`	string	No	Player avatar URL.
`extra_data`	string	No	Opaque value returned unchanged in every bet, win and rollback callback for this session.
`expires_in_minutes`	number	No	Session lifetime. Default `30`.
`demo_session`	boolean	No	Opens a session without wallet movements. Your account must allow demo sessions.

The legacy demo field is not supported. Sending "demo": true returns 400; use demo_session instead.

json

{
  "user_id": "player-123",
  "username": "Ana",
  "game": "amazonia-adventure",
  "currency": "BRL",
  "lang": "en-US",
  "balance": 100.0,
  "extra_data": "brand=acme;device=mobile",
  "expires_in_minutes": 60
}

Response

200 OK

Field	Type	Description
`game_url`	string	URL that opens the game. Load it in a new window or an iframe.
`session_token`	string	Session identifier. KOI sends it as `session_token` in callbacks.

json

{
  "game_url": "https://play.koigames.app/b3e1f6d2c9a84f0e",
  "session_token": "b3e1f6d2c9a84f0e"
}

Errors

Status	When
`400`	Unknown currency code, or `"demo": true` was sent.
`401`	Missing or invalid access token, or the game is not enabled for your account.
`403`	`demo_session` requested but not allowed for your account, or launches are temporarily blocked by the platform integrity check.
`422`	Validation failed. The body lists the invalid fields.

See Errors for the response format.

Embedding

The game runs in the browser and connects to KOI over secure WebSockets. When embedding in an iframe, allow full screen and autoplay:

html

<iframe src="GAME_URL" allow="fullscreen; autoplay" style="border:0;width:100%;height:100%"></iframe>

Open a new session for every launch. Sessions expire after expires_in_minutes; an expired session cannot place bets.