Sessions

Opening and consuming MusterBox match sessions from the SDK.

A match session is the per-player context your game runs in. It is issued for a real match, to a real participant, through a valid game key — and it is single-use.

Open a session

use musterbox_config::Environment;
use musterbox_sdk::{GameEnvironment, MatchId};

let ctx = sdk.open_session(Environment::Sandbox, 1042)?;
// ctx.session_id, ctx.token, ctx.expires_at, ctx.context

Browser:

const s = await box.openSession({ environment: "sandbox", matchId: 1042 });

Under the hood: POST /api/v1/game-sdk/{gameId}/sessions with the bearer access token and the x-game-key header. The response:

Field	Meaning
sessionId	Backend id of the session
token	Single-use session token for result submission
expiresAt	Session expiry — the TTL is 10 minutes
context	{ tournamentId, matchId, participantId, slot }

Start-gate rules

A session is refused (403) when:

• the game is not published,
• the game key is invalid for the requested environment,
• the key’s allowed origins do not include the request origin,
• the key lacks the session scope, or
• the player is not a participant of the given match.

Origin is read from the request Origin/Referer header, so the game key’s origin binding is what protects browser builds.

Consume the session

The token is consumed when you submit a result (POST results). It is verified as:

• a real session token hash,
• not already consumed,
• not expired,
• bound to this user and this match.

Because consumption is single-use, each result claim uses its own session.

Session status

The SDK exposes teammate session status and player context through get_session_status() and player_context(), so your UI can reflect whether a match session is open, pending, or validated.

Multi-session flows

Each player device opens its own session; sessions are never shared. Mutually-confirmed results are described in Second session & mutual claims.

Next: Events & realtime.