> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musterbox.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```rust theme={"dark"}
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:

```ts theme={"dark"}
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](/api/api-overview)). 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](/guides/second-session-mutual-claims).

Next: [Events & realtime](/sdk/events).