Provider API/Game launch
Game launch
API · Operator → Boss HubPOST/v1/game/launch
Opens a real-money game session for a player. The returned launch_url is single-use and valid for expires_in seconds (60 s by default); redirect the player to it. The player record is created automatically on the first launch, per site and environment. Requires the game.launch scope.
Headers
| Header | Description |
|---|---|
| X-Operator-Id | Your operator ID |
| X-Timestamp | Unix seconds. Rejected outside ±30 s |
| X-Signature | hex(HMAC_SHA256(secret, ts + "." + METHOD + "." + path?query + "." + body)) |
| X-Request-Id | Required, at most 128 characters. The same ID and body return the first response (4xx included); a different body gets a 409. See Idempotency |
| X-Api-Key | Optional. Selects the right secret when you have several keys |
RTP: If your site has a market, the variant is chosen by the market rules. Boss Originals games need an approved certification for that market on the game’s live version. For games of external providers (e.g. EGT) certification is the provider’s responsibility; every variant counts as certified. The requested variant is used if eligible (certified and RTP ≥ the market’s minimum RTP); otherwise the lowest eligible variant applies (v92 → v94). If none is eligible: 403 MARKET_RESTRICTED. On a site without a market, the requested variant is used, otherwise the site and operator preference, otherwise the game’s default.
Credit limit: When the limit is exceeded, only new sessions are blocked. Open sessions keep playing.
Country restrictions: A provider or a game may block some countries; the list is blocked_countries in the GET /v1/games response. If the effective country is on the list, you get 403 COUNTRY_BLOCKED. If the list is not empty and the country is unknown (neither country was sent nor is it on the player record), you get 403 COUNTRY_REQUIRED. With an empty list the result does not change even if you send no country.
200Session opened
{
"launch_url": "https://api.example.com/s/7Hq…",
"session_id": "ses_01HF3K7M",
"expires_in": 60,
"limits": {
"currency": "USD",
"min_bet": 0.20,
"max_bet": 100.00,
"default_bet": 1.00,
"source": { "min_bet": "platform", "max_bet": "site" }
}
}402Credit limit exceeded or operator suspended
{
"code": "CREDIT_LIMIT",
"message": "Credit limit exceeded; no new game can be opened.",
"request_id": "req_01HF3Q2N",
"details": { "source": "credit" }
}403No RTP variant eligible under the market rules
{
"code": "MARKET_RESTRICTED",
"message": "A market rule does not allow this game.",
"request_id": "req_01HF3Q2P",
"details": { "source": "market_rule" }
}Response fields
| Field | Type | Description |
|---|---|---|
| launch_url | uri | The single-use address for the player to open. |
| session_id | string | The game session. Arrives as session_id in callbacks. |
| expires_in | integer | How long launch_url stays valid, in seconds. |
| limits | object | Effective bet limits of this session. Fields: limits. |
Opening launch_url
When the player’s browser opens launch_url, Boss Hub calls your authenticate callback, then redirects the player to the game client. The address opens once; if you use an iframe, allow the game addresses.
| HTTP | Code | Meaning |
|---|---|---|
| 302 | Redirect to the game | |
| 410 | LAUNCH_TOKEN_EXPIRED | The address was already opened, has expired, or the sessions were ended. Request a new launch |
| 404 | NOT_FOUND | Unknown address |
| 403 | INVALID_TOKEN, PLAYER_BLOCKED, INTERNAL_ERROR | Your authenticate reply rejected the player |
| 503 | PROVIDER_UNAVAILABLE | authenticate did not answer or did not answer HTTP 200, or the game provider could not open the session (details.provider_code) |
| 500 | INTERNAL_ERROR | authenticate answered HTTP 200 but the body is not JSON |
Demo session
POST /v1/game/demo needs no signature and no X-Request-Id. It works only for publicly listed games that are live or ready for release. It is limited to 60 requests per minute per IP; it creates no player or ledger record.
POST /v1/game/demo HTTP/1.1
Host: staging.example.com
Content-Type: application/json
{
"game_id": "sultans-ember",
"currency": "USD",
"language": "tr"
}200Demo address
{
"launch_url": "https://play.example.com/demo/…"
}Error codes
| Code | HTTP | Meaning |
|---|---|---|
| INVALID_SIGNATURE | 401 | Signature headers missing, or the signature could not be verified |
| TIMESTAMP_SKEW | 401 | X-Timestamp is outside ±30 s |
| CREDIT_LIMIT | 402 | Credit limit exceeded; no new sessions (details.source: credit) |
| OPERATOR_SUSPENDED | 402 | Operator suspended, or no production approval on Live |
| IP_NOT_ALLOWED | 403 | IP is not on the allowlist |
| SCOPE_MISSING | 403 | The game.launch scope is missing |
| SCOPE_DENIED | 403 | site_id is unknown, not yours, or not the site of your site-bound key |
| MODULE_DISABLED | 403 | A game of an external provider and the providers module is off |
| GAME_DISABLED | 403 | The game cannot be opened on this site; the reason is in details.source (below) |
| SITE_DISABLED | 403 | The site is off, or a site called on Live is not in Live status |
| MARKET_RESTRICTED | 403 | No RTP variant is eligible under the market rules |
| PLAYER_BLOCKED | 403 | Player restricted, or the bet cap of a player restriction is below the game’s minimum bet (details.source: player_restriction) |
| COUNTRY_BLOCKED | 403 | The game or the provider blocks the player’s country (launch and demo) |
| COUNTRY_REQUIRED | 403 | The game has country restrictions and the player’s country is unknown: send country |
| NOT_FOUND | 404 | No game with this game_id; for demo, the game is not publicly listed |
| DEMO_NOT_AVAILABLE | 404 | Demo: the provider offers no demo for this game |
| REQUEST_ID_CONFLICT | 409 | Same X-Request-Id, different body |
| REQUEST_IN_PROGRESS | 409 | The same X-Request-Id is still being processed |
| SITE_REQUIRED | 422 | Operator-wide key and several sites: site_id is needed |
| VALIDATION_ERROR | 422 | Missing or invalid field (details.fields), missing X-Request-Id, or an invalid recommendation_id (details.field) |
| INVALID_JSON | 422 | The body could not be read as JSON |
| CURRENCY_NOT_SUPPORTED | 422 | The currency is not supported by the site, the wallet settings or the game, or the player has another currency |
| RATE_LIMITED | 429 | Rate limit exceeded |
| PROVIDER_NOT_CONNECTED | 503 | The provider is not connected in this environment |
| PROVIDER_UNAVAILABLE | 503 | Demo: the provider could not be reached |
| MAINTENANCE | 503 | Platform or provider maintenance (details.source: maintenance) |
| GAME_DISABLED details.source | Reason |
|---|---|
| platform | The game or provider is off on the platform |
| access | You have no access to the provider, or the provider is not open in this environment (on Live it must have been taken live); or the game is not in your selected game list |
| game | The game is retired, or has no live version and is not in early access |
| operator_rule | Closed by your operator-wide rule |
| site_rule | Closed by your site rule |
| limits | No bet limits are defined in this currency |
Order of checks: JSON parsing and body validation, timestamp, signature, IP, rate limit, X-Request-Id, scope; then game, site, maintenance, operator, site status, module, game access and rules, market, credit, country, provider connection, currency, limits and player. The code of the first closed step is returned.