Sessions

A session represents one game instance. Create it server-side, pass the JWT token to your client. Sessions expire after 5 minutes if not joined.

Create a session

POST

/v1/sessions

Create a new game session and receive a session token.

curl -X POST https://api.beta-gamer.com/v1/sessions \
  -H "Authorization: Bearer bg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "game":      "chess",
    "mode":      "live",
    "matchType": "matchmaking",
    "players": [
      { "id": "user_123", "displayName": "Alex" },
      { "id": "user_456", "displayName": "Jordan" }
    ]
  }'

Response

{
  "sessionId":       "a1b2c3d4-...",
  "sessionToken":    "eyJhbGciOiJIUzI1NiJ9...",
  "expiresIn":       300,
  "game":            "chess",
  "mode":            "live",
  "matchType":       "matchmaking",
  "roomCode":        null,
  "players":         [{ "id": "user_123", "displayName": "Alex" }, ...],
  "theme":           { "primaryColor": "#ff6b00" },
  "webhooksEnabled": true
}

Get a session

GET

/v1/sessions/:id?game=chess

Retrieve session status and result after the game ends.

{
  "id":        "a1b2c3d4-...",
  "game":      "chess",
  "mode":      "live",
  "matchType": "matchmaking",
  "status":    "ended",
  "players":   [...],
  "result": {
    "winner":    "user_123",
    "reason":    "checkmate",
    "duration":  342,
    "moveCount": 38,
    "pgn":       "1. e4 e5 2. Nf3 ..."
  }
}

Request fields

Field	Type	Required	Description
`game`	string	✓	chess \| checkers \| connect4 \| tictactoe \| subway-runner
`mode`	string	—	live (default) \| test \| training
`matchType`	string	—	matchmaking (default) \| private \| bot
`players`	array	✓*	Array of { id, displayName }. Not required for training mode.
`playerCount`	number	—	Training mode only. 1 or 2. Defaults to 1.

Session lifecycle

pending→active→ended

pending — session created, waiting for players to connect via WebSocket.
active — both players connected, game in progress.
ended — game finished. Result is available. Webhook has been dispatched (live mode).

Token expiry

Session tokens expire 5 minutes after creation. If a player hasn't connected within that window, create a new session. Once a game is active, the token is no longer needed — the WebSocket connection is maintained independently.

Beta Gamer GaaS API — questions? support@beta-gamer.com