Skip to content
OrbiSportbook Docs

Player sessions

Your platform authenticates the player and completes its registration, CPF validation, KYC and eligibility checks before requesting a sportsbook session. Your server then identifies that existing player to OrbiSportbook with externalPlayerId; there is no separate registration or player login inside the iframe.

The endpoint finds or creates an internal sportsbook record linked to that id and returns a single-use launch token. Creating this record is not player onboarding or identity verification by OrbiSportbook.

Endpoint, server to server
POST /api/v1/integration/sessions
Launch token
single use, 120 s
Session
12 h absolute, idle timeout

Create a session

Section titled “Create a session”
POST /api/v1/integration/sessions HTTP/1.1
Host: api.orbisportbook.com
Content-Type: application/json
X-Tenant-ID: demo-embed
X-API-Key: <your integration API key>


{"externalPlayerId": "player-42", "displayName": "Maria", "path": "/live", "locale": "pt-BR"}
Field Type
externalPlayerId string required Your stable player id, at most 128 characters. The same id within a tenant is always the same player; it is the playerId of every wallet call.
displayName string optional Shown in the sportsbook, at most 64 characters. Updated when it changes. Default Player.
currency string optional Must equal the tenant currency when sent.
cpf string deprecated Accepted and ignored for compatibility. Do not send CPF; it is neither validated nor stored.
path string optional Deep link put in launchUrl: /, /live, /live/{sportId}, /sport/{sportId}, /competition/{id}, /event/{eventId}, /my-bets.
locale string optional en or pt-BR, put in launchUrl. Default: the tenant locale.

Unknown fields are refused (400 validation), so typos do not pass silently.

Response

Section titled “Response”

200 OK:

{
  "launchToken": "lt_NIpjVSCtwQlG0iLUbF9T7WeY84YSVs3pVQeLxbbH1O0",
  "launchExpiresAt": "2026-10-16T03:01:22.081091Z",
  "launchUrl": "https://api.orbisportbook.com/?tenant=demo-embed&launch=lt_NIpjVSCtwQlG0iLUbF9T7WeY84YSVs3pVQeLxbbH1O0&path=%2Flive&locale=pt-BR",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "player": {
    "id": "pl_bd387263c326f44e90808bde",
    "tenantId": "demo-embed",
    "externalId": "player-42",
    "status": "active",
    "displayName": "Maria",
    "currency": "USD",
    "kycStatus": "verified",
    "createdAt": "2026-10-16T02:43:38.465403Z"
  }
}
Field
launchToken Give this to the page: pass it to the embed SDK (launchToken option or setLaunchToken()). Single use, expires at launchExpiresAt.
launchUrl The same token as a ready-made iframe URL, for integrations without the SDK.
token The session token itself. Keep it on your server (or ignore it): never put it in a URL or a page. It stays in the response for backward compatibility.
player Internal sportsbook record linked to your player (abridged above). For players created through this integration, kycStatus: verified records delegation to the operator. It is not a KYC result, document check or certification performed by OrbiSportbook.

The origin of launchUrl is the platform’s configured sportsbook URL (SPORTSBOOK_URL); when unset, the origin your request was sent to.

Errors

Section titled “Errors”
Status code When
401 unauthorized Missing or wrong X-API-Key, or the tenant has no key. Every failure is audited with the caller’s IP.
400 validation Bad field; details.field names it (externalPlayerId, displayName, currency, path, locale), or an unknown field.
403 account_blocked The player is blocked or closed on the platform.
403 account_paused, account_closed An existing local player restriction prevents the session.
404 not_found Unknown tenant (X-Tenant-ID).
503 unavailable The tenant is suspended or the service is temporarily unavailable. Retry later.

Launch tokens

Section titled “Launch tokens”

A launch token is how the session reaches the iframe without ever being put in a URL. The sportsbook exchanges it once, at start-up or when it receives set_launch_token:

POST /api/v1/integration/launch
Content-Type: application/json
X-Tenant-ID: demo-embed


{"launchToken": "lt_NIpjVSCtwQlG0iLUbF9T7WeY84YSVs3pVQeLxbbH1O0"}
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "player": { "id": "pl_bd387263c326f44e90808bde", "…": "…" } }

You never call this endpoint yourself; the iframe does. It keeps the session token in memory and in sessionStorage for that iframe, and removes launch from its own address before anything else loads.

Rule
Single use The exchange marks the token used in the same database statement: a second exchange (a replayed or shared URL, the browser history) gets 401 with details.reason: "launch_token_used", and the replay is audited.
Expiry 120 seconds after it was issued (launchExpiresAt): 401, launch_token_expired. Create the session right before you render the sportsbook.
Tenant A token only works for its own tenant: elsewhere it is launch_token_invalid, like an unknown token.
Session The session must still be alive: a logged-out or expired session gives 401 (unauthorized or session_expired).
Storage Only a SHA-256 hash of the token is stored. Used and expired tokens are deleted after a day.

When the exchange fails at start-up, the sportsbook stays anonymous and sends your page an error event (code = the reason) followed by session_expired, so the SDK’s onSessionExpired can fetch a fresh token.

Session lifetime and refresh

Section titled “Session lifetime and refresh”
  • A session lasts at most 12 hours and ends after the jurisdiction’s idle timeout (60 minutes for .com tenants, 30 minutes for Brazil). Every authenticated call from the iframe (balance, bets, My Bets) counts as activity; browsing odds does not.
  • Each call to integration/sessions opens a new session; earlier sessions of the player keep working until they expire. When the player logs out of your site, call logout() on the SDK to end the sportsbook session too.
  • To refresh, call integration/sessions again and send the new launch token to the iframe. With the SDK, return it from onSessionExpired:
OrbiSportbook.mount('#sportsbook', {
  url: 'https://api.orbisportbook.com',
  tenant: 'your-tenant',
  launchToken,
  // called when the sportsbook session ends (idle, expiry, refused token)
  onSessionExpired: async () => {
    const res = await fetch('/my-site/sportsbook-launch', { method: 'POST' }); // your endpoint
    return res.ok ? (await res.json()).launchToken : null; // null: stay logged out
  },
});

The same mechanism logs a player in without reloading the iframe: after your login dialog, call sb.setLaunchToken(newLaunchToken).

Current API compatibility

Section titled “Current API compatibility”
  • Sessions use the client platform’s stable externalPlayerId, scoped to the tenant. The same ID in the same tenant reuses the player; different tenants have separate players.
  • No profile requires CPF, including BR. The legacy cpf string is accepted and ignored: the integration does not validate it, query CPF lists or store it.
  • Existing players retain their internal ID. A previously stored CPF does not need to be resent and is not used for CPF betting checks on these integrated players.
  • Registration, CPF, KYC and eligibility remain the client platform’s responsibility. Do not send CPF or identity documents in session requests.
  • Local blocks, closures, restrictions and the remaining betting controls still apply.
  • kycStatus: verified records delegation to the operator; it does not mean OrbiSportbook performed KYC.