Private Matches

Private matches let two specific players play each other using a 6-character room code. No matchmaking queue — you control who plays who.

Flow

1. 1
   Host creates a session — POST /sessions with matchType: "private". Response includes a roomCode (e.g. "A3F9C1").
2. 2
   Share the room code — Your app delivers the code to the friend — via chat, copy link, QR code, etc.
3. 3
   Friend joins — Friend calls POST /sessions/join with the room code. Receives their own session token.
4. 4
   Both connect — Both players initialise the game client with their respective tokens. Game starts.

Create private session (host)

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

{
  "sessionId":    "a1b2c3d4-...",
  "sessionToken": "eyJhbGci...",
  "roomCode":     "A3F9C1",
  "matchType":    "private",
  ...
}

Join private session (friend)

curl -X POST https://api.beta-gamer.com/v1/sessions/join \
  -H "Authorization: Bearer bg_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "roomCode": "A3F9C1",
    "game":     "chess",
    "player":   { "id": "user_456", "displayName": "Jordan" }
  }'

Room code details

• Room codes are 6 characters, uppercase alphanumeric (e.g. A3F9C1).
• Codes are unique per tenant — the same code can exist across different tenants without conflict.
• A code is valid until the session moves to active (both players joined) or expires after 10 minutes.
• Subway Runner does not support private matches — it is single-player only.