Session Flow

Overview

A game session represents a single play session for one player in one game. Sessions are created via the Gateway API and govern the entire lifecycle of game interactions.

---

Full Integration Flow

sequenceDiagram
    participant Operator
    participant Beexar
    participant Game as Game Frontend
    participant Wallet as Operator Wallet

    Note over Operator,Wallet: 1. Session Creation
    Operator->>Beexar: POST /api/v1/softswiss/launcher/real
    Beexar->>Beexar: Validate signature (HMAC-SHA256)
    Beexar->>Beexar: Create session (30 min TTL)
    Beexar-->>Operator: { launch_url }

    Note over Operator,Wallet: 2. Game Load
    Operator->>Game: Embed launch_url in iframe
    Game->>Beexar: Load with session token
    Beexar->>Wallet: POST /balance
    Wallet-->>Beexar: { balance: "500.00" }
    Beexar-->>Game: Show game UI with balance

    Note over Operator,Wallet: 3. Gameplay
    Game->>Beexar: Player places bet
    Beexar->>Wallet: POST /betwin (bet + win, finished=true)
    Wallet-->>Beexar: { balance: "509.80", transactions }
    Beexar-->>Game: Show result

    Note over Operator,Wallet: 4. Round with Rollback
    Game->>Beexar: Player places bet
    Beexar->>Wallet: POST /betwin (bet)
    Wallet-->>Beexar: 200 OK
    Note right of Beexar: Game engine error
    Beexar->>Wallet: POST /rollback (original bet)
    Wallet-->>Beexar: { balance: "509.80" }

---

Session Token

The session token is a 64-character hexadecimal string that uniquely identifies the session.

Property	Value
Format	64 hex characters ([a-fA-F0-9]{64})
Created by	Beexar Gateway
Used by	Game frontend (passed as URL query parameter)
Lifetime	30-minute sliding window: expires 10–30 min after the last action, 24 h after launch at most

The token is embedded in the launch_url:

https://games.beexar.com/dice/casinoxyz/dice-game?token=a1b2c3d4e5f6...

Demo tokens are prefixed with demo_:

https://games.beexar.com/dice/casinoxyz/dice-game/demo?token=demo_a1b2c3d4e5f6...

---

Session States

stateDiagram-v2
    direction LR
    [*] --> Created: POST /api/v1/softswiss/launcher/*
    Created --> Active: Game loaded
    Active --> Active: Player activity
    Active --> Expired: TTL expired
    Active --> Closed: Player exits
    Expired --> [*]
    Closed --> [*]

State	Description
Created	Session token generated, awaiting game load
Active	Game is loaded and the player is playing
Expired	No activity for the rest of the window, or 24 h since launch
Closed	Player closed the game or navigated away

---

Sliding Session TTL

Sessions use a sliding window mechanism:

Property	Value
Initial TTL	30 minutes
Extension trigger	Player activity (any game request, balance reads included)
Extension threshold	When remaining TTL < 10 minutes
Extension amount	Reset to 30 minutes
Absolute cap	24 hours from launch — never extended past it

flowchart LR
    Action["Player Action"] --> Check{"TTL < 10 min?"}
    Check -- Yes --> Extend["Extend to 30 min"]
    Check -- No --> NoOp["No change"]
    Extend --> Active["Session Active"]
    NoOp --> Active

This means an active player’s session does not expire during gameplay (up to the 24-hour cap). Because the window is only reset once less than 10 minutes remain, an idle session expires 10 to 30 minutes after the player’s last action.

Note

Session extension is fire-and-forget — if the extension fails for any reason, the player’s current action still succeeds. The session simply won’t be extended.

---

Real-Money vs Demo Sessions

Property	Real-Money	Demo
Endpoint	POST /api/v1/softswiss/launcher/real	POST /api/v1/softswiss/launcher/demo
Token prefix	(none)	demo_
Wallet callbacks	Yes (/balance, /betwin, /rollback, /finish)	No
Balance source	Operator wallet	Beexar virtual wallet
TTL	30 min sliding, 24 h max	30 min sliding, 24 h max
Analytics	Recorded	Not recorded

Caution

Demo sessions do not trigger any wallet callbacks. All balance operations happen in Beexar’s virtual wallet. Demo bets, wins, and rounds are not recorded in analytics.

---

Session Expiry

When a session expires:

1. Every request with its token is refused with INVALID_SESSION. The game shows a “session expired” screen; the player relaunches from your lobby, which creates a new session (if you passed return_url, the game’s Home menu leads there).
2. Expiry itself sends no wallet request — no /rollback, no /finish. A bet you accepted stands: a round still open is completed by the game server like any other round (/betwin with the win, or /finish, on the same round_id and with the session_id of the session that opened it — these do not need a live session). /rollback is sent only for a bet whose round could not go ahead (a failed or unconfirmed wallet call), never because a session expired.
3. Beexar keeps the session’s ID in its round history; the token opens nothing after expiry.

---

Reconnection

If a player disconnects and reconnects (e.g., refreshes the page):

1. The game frontend loads with the same session token from the URL
2. If an in-progress round exists (for example, a Candy Cash drop that was still playing), the game resumes it
3. No duplicate transactions — idempotency via id_provider

Note

All operator communication with Beexar is standard HTTP/REST. You do not need to implement WebSocket or any other protocol.