Authenticate & mint a launch token

Minting a launch token is how you authenticate a player into LootBox Solutions: you assert, signed with your API key, that playerExternalId is a valid player of yours, and receive a short-lived URL to embed.

Request

POST https://{operator}.app.lootboxsolutions.com/api/s2s/launches

{
  "playerExternalId": "u_8431",
  "gameKey": "mystery_box",
  "target": { "boxId": 42 },
  "locale": "en",
  "currency": "EUR",
  "returnUrl": "https://casino.example/lobby",
  "balanceMinor": 12000
}

Field	Required	Notes
playerExternalId	✅	Your stable opaque player id (1–190 chars).
gameKey	✅	mystery_box for a box, or upgrader for the Upgrader game. Must be one of the operator’s enabled games.
target	✅	What to open to. { "boxId": <int> } for a single box. Omit boxId (or send {}) to open into the lobby. For a game target like upgrader, send an empty target: {} — the game has no box to pin. See below.
locale	—	BCP-47-ish code (e.g. en, pt-BR). Sets the session language. See Localization.
currency	—	ISO-4217 code. Overrides the operator default for this session; must be one of your configured currencies.
returnUrl	—	Where the game app sends the player on exit (max 2048 chars, must be a URL).
balanceMinor	—	Optional balance snapshot. Lets the game app show a balance immediately and skip the first wallet.balance round-trip.
funding	—	player (default) or operator for an operator-funded (free/bonus) open — no wallet debit. Honoured because the launch is signed by your backend; pair with target.autoOpen for a free box that auto-plays, or leave autoOpen off for a player-clicked “Open your free box” CTA.
nuggetsRate	—	Your current number of Nuggets per one unit of the player’s currency (integer, 1 or more). The game app uses it to name a Nuggets prize “17,500 Nuggets” from the prize’s value; omitted, it names the prize “Nuggets worth $25.00”. Send it only if you run Nuggets.
displayMode	—	How the game app shows the player’s amounts: money (the default when omitted, “$24.96”) or credits. In credits mode every price and value keeps the money format’s digits and decimals without the currency symbol: shown on its own it is your Credits icon followed by the number (“24.96”), inside a sentence or on a button it reads “24.96 Credits” (“Open for 50.00 Credits”). One Credit is one unit of the session currency; only the look changes.
creditsIcon	—	Only with displayMode: "credits". The name of the built-in icon drawn before each amount, in kebab case: one of package, boxes, gift, sparkles, star, trophy, crown, gem, coins, banknote, credit-card, shopping-bag, shopping-cart, tag, ticket, layers, layout-grid, flame, zap, rocket, target, swords, shield, dices, gamepad-2, puzzle, ghost, cat, dog, leaf, sun, moon, snowflake, car, plane, music, headphones, camera, palette, heart, hexagon (drawn with its inside filled at 25% of creditsColor). An unknown or missing name draws coins.
creditsIconUrl	—	Only with displayMode: "credits". The http/https URL of your own SVG icon, drawn instead of creditsIcon (max 2048 chars). By default only its shape is used: the game app fills it with creditsColor, whatever colours the file has. The player’s browser then loads it from your site as a CSS mask, so the file must be served with a CORS header that allows the game app’s origin (Access-Control-Allow-Origin: * is enough); without it the icon does not show.
creditsIconOwnColors	—	Only with creditsIconUrl. true draws your SVG in its own colours instead of filling it with creditsColor (no CORS header needed). Default false.
creditsColor	—	Only with displayMode: "credits". The colour the Credits icon is drawn in, built-in or your own, as a #rrggbb hex (“#26d985”). Omitted, the icon takes the text colour of the amount it stands beside.
fundingRounds	—	Only with funding: "operator". Caps how many operator-funded opens this session grants — for the target box only; every other box the player opens is player-funded. Omit for uncapped (legacy behaviour: every open of the target box is operator-funded). Integer 1–100.

Targeting

• A specific box page — target: { "boxId": 42 }. The iframe opens on that box’s page. This is where the recommended widget sends a player after a card click.
• A box, purchased and auto-played on arrival — target: { "boxId": 42, "autoOpen": true }. The box is opened (debited + played) as soon as the session boots — used for the widget’s “Buy now”, where the player confirms on the card and lands on the box page mid-spin. Pass a clientActionId to keep the auto-open idempotent across a refresh.
• The lobby — target: {} (full-iframe browsing). Lands in the catalog. Requires the full iframe. Not used by the widget — the widget redirects the parent to a box page rather than navigating inside a list.
• A game target — gameKey: "upgrader" with target: {}. The session boots straight into the Upgrader, which stakes against a price band rather than opening a box, so there is no box to pin (a boxId is rejected).

Response — 201

{
  "launchToken": "lt_…",
  "launchUrl": "https://{operator}.app.lootboxsolutions.com/play?token=lt_…",
  "expiresAt": "2026-06-03T12:01:00Z"
}

• TTL: 60 seconds, single-use — consumed by the game app’s first session/init. Mint one per embed.
• Tokens are stored hashed; a leak exposes nothing usable.
• Drop launchUrl into an <iframe src> (add &parent=<your-origin> to enable host messaging — see Embedding).

Errors

code	HTTP	when
GAME_DISABLED	403	gameKey not in the operator’s enabled games
TENANT_SUSPENDED	403	operator is suspended
UNKNOWN_BOX	404	boxId not found
BOX_NOT_PLAYABLE	409	box inactive or has no current version
UNSUPPORTED_CURRENCY	422	currency not configured for the operator
validation error	422	malformed input

Refresh & deep-linking

Because tokens are single-use and short-lived, a hosting page that needs to restore the iframe after a refresh should re-mint on the server and re-embed. The iframe also reports its current location so your page can rebuild the right launch — see Refresh & deep-linking.