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`.
`target`	✅	What to open to. `{ "boxId": <int> }` for a single box. Omit `boxId` (or send `{}`) to open into the lobby — 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.
`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.

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.