# Sessions & launch

> Creating a session, opening the launch URL, session lifecycle, closing early, and reading what a player has in play.

Source: https://casinoapipro.com/docs/sessions
A session binds one player to one game for one sitting, and produces the launch URL you open in their browser. It is the only object you need to create in order to start play.

## Create a session

`POST /v1/sessions` — auth: operator-api

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `game_id` | string | yes | The game's slug (`"mines"`) or id. Slugs are stable and easier to read in logs. |
| `player_id` | string | yes | Your identifier for the player. Opaque to us, scoped to your account. |
| `currency` | string | yes | ISO 4217, e.g. `"GHS"`. Must be enabled for both your account and the game. |
| `ttl_seconds` | integer | no | Shorten the session lifetime. Cannot exceed your account default. |
| `brand_id` | string | no | Which of your brands this sitting belongs to, if you run more than one. |
| `player_name` | string | no | Display name shown in multiplayer games, 1–40 characters. Never used for identity, and never matched against anything. Sent on any session it replaces the stored name; omitted, the stored one is kept. |
| `return_url` | string | no | Where the launcher sends the player when they close the game. |

> **A name you send is shown as you sent it**
>
> A player who arrives without `player_name` appears as their `player_id` with all but the first and last character masked — safe, and unreadable. A name you supply is shown verbatim instead, because you chose it for this purpose: we do not mask it again, so `"***417"` stays `"***417"` rather than becoming `"***7"`. Send a username or a handle you are happy for other players to see — never a phone number or anything a player signs in with.

_cURL_

```bash
curl -X POST https://api.casinoapipro.com/v1/sessions \\
  -H "Authorization: Bearer $ACCESS_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "game_id": "mines",
    "player_id": "your_player_42",
    "currency": "GHS",
    "return_url": "https://your-casino.com/lobby"
  }'
```

_JavaScript_

```js
const session = await api.post("/v1/sessions", {
  game_id: "mines",
  player_id: player.id,
  currency: player.currency,
  return_url: "https://your-casino.com/lobby",
});

res.redirect(session.launch_url);
```

_PHP_

```php
$session = $client->post("/v1/sessions", [
  "game_id"    => "mines",
  "player_id"  => $player->id,
  "currency"   => $player->currency,
  "return_url" => "https://your-casino.com/lobby",
]);

header("Location: " . $session["launch_url"]);
```

```json
{
  "session_id": "sess_kgv5ws4duteqwhvjobok",
  "launch_url": "https://games.casinoapipro.com/play?token=eyJhbGciOi…",
  "expires_at": "2026-08-29T19:11:56.237Z",
  "game": { "id": "d533d22e…", "slug": "mines", "name": "Mines" },
  "player_id": "your_player_42",
  "currency": "GHS"
}
```

## Opening the launch URL

Redirect to it, or embed it in an `<iframe>` with `allow="autoplay; fullscreen"`. The token inside is scoped to one operator, one player and one game, and it is short-lived.

> **Do not cache the launch URL**
>
> Mint a fresh session each time the player opens the game. A stored URL will expire, and a shared one is a URL that plays on someone else's balance.

## Lifecycle

- `ACTIVE` — created, and playable until it expires.
- `CLOSED` — ended by you, with [close](/docs/sessions#close). A player closing the game does not close the session.
- `EXPIRED` — passed `expires_at`. Marked on the first request after that moment.

A session ending — by expiry or by you — does not touch money already in play. See [what a player has in play](/docs/sessions#in-play).

Sessions are not idempotent — calling create twice mints two sessions. That is harmless, but prefer one per launch so your reporting matches the player's experience.

## Fetch a session

`GET /v1/sessions/{sessionId}` — auth: operator-api

```bash
curl https://api.casinoapipro.com/v1/sessions/sess_kgv5ws4duteqwhvjobok \\
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Close a session early

`POST /v1/sessions/{sessionId}/close` — auth: operator-api

Use this when a player self-excludes mid-sitting, or when you need to stop play immediately. From that moment the session refuses every request: no new stake, and no decision on one already placed — including a cash-out.

> **Closing moves no money**
>
> It does not settle, void or refund anything. A Goal Jet stake already riding stays on its flight and settles when the flight ends — at the crash, since a closed session cannot cash out. A round that waits on the player, such as a Mines board, stays `OPEN` against the player, not the session: they can finish it from a new session, and until then cannot open another round of that game. To release one that never took a stake, see [voiding a stuck round](/docs/history#void).

```bash
curl -X POST https://api.casinoapipro.com/v1/sessions/sess_kgv5ws4d/close \\
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## What a player has in play

Stakes and open rounds are held against the player, not the session. A new session — which you mint every time the player opens a game — sees everything the last one left: a stake on the current flight, or an unfinished board. Nothing is lost by the player closing and reopening, and nothing needs restoring by you.

For your own servers, list what is still in play with the history API:

```bash
curl "https://api.casinoapipro.com/v1/rounds?player_id=your_player_42&status=OPEN" \\
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

A Goal Jet stake is an `OPEN` round from the moment it lands until it is cashed out or its flight ends, so this answers "does this player have money riding" as well as "is a board unfinished". See [rounds](/docs/history#rounds) for the fields.

> **The game reads the same state itself**
>
> The launcher we host reads the player's stakes with their session token — `GET /v1/game/crash/state` for Goal Jet, `GET /v1/game/state` for the instant games — and receives their Goal Jet stakes on its live connection with every update. Those are the game's own endpoints rather than part of the operator API: they take the player's token, not your credentials, and you do not need to call them.

## Next

- [Wallet integration](/docs/wallet) — what happens once the player bets.
- [Provably fair](/docs/provably-fair) — what the launcher commits to.