Server-to-server API

The server-to-server (S2S) API is how your backend talks to LootBox Solutions. It mints sessions, reads the catalog, drives the gameplay lifecycle (purchase / cashout / cancel / history), and handles admin SSO.

All S2S endpoints are under https://{operator}.app.lootboxsolutions.com/api/s2s and are HMAC-signed with your inbound API key.

Endpoints

Method	Path	Purpose
POST	/launches	Authenticate a player & mint a session
GET	/boxes	Read the box catalog
GET	/boxes/{boxId}	Read one box’s prize table (values, images, odds)
GET	/boxes/{boxId}/version	Resolve the live current version to open (no prize table)
POST	/purchase	Open a box (atomic) or pre-pay into the vault
POST	/cashout	Cash back a won inventory item
POST	/cancel	Refund an unopened (held) box
GET	/history	List transactions (purchases, opens, refunds, cashbacks)
POST	/admin-sso	Mint an embedded-admin SSO link
GET	/health	Liveness check

Conventions

• Auth: every call carries X-Key-Id, X-Timestamp, X-Signature. See Authentication.
• Money: integer minor units; currency accompanies every amount.
• Time: ISO 8601 UTC.
• Ids: boxes use integer ids; rounds, orders, and other resources use opaque public ids (r_…, fo_…) safe to expose to players.
• Idempotency: write endpoints accept an idempotencyKey (or clientActionId) so retries are safe. Reusing a key returns the original result instead of acting twice.
• Errors: a JSON body { "error": { "code": "…", "message": "…" } } with an appropriate HTTP status. The full list is in the error reference.

Relationship to the player API

Purchase, cashout, and cancel also exist on the bearer-authenticated player API that the game app drives. The S2S versions here are for backend-driven integrations (Model B): same effects, same wallet calls, signed with your API key instead of a session token, and acting on behalf of a playerExternalId you supply.