Game Sessions and Invites

Game Sessions and Invites

A game session is a pre-game room. One player creates it and gets back a 6-character join_code that others use to join. A session carries the roster of peers, and it is how the recommended P2P handshake shares the host's address. Calls need the API key and the session token.

Sessions

• POST /v1/game-session creates a room. You can set max_players, mark it private, and attach a public_addr (ip and port) for the host.
• POST /v1/game-session/{id}/join joins by id.
• POST /v1/game-session/{id}/heartbeat keeps a peer alive and returns the current peer list.
• GET /v1/game-session/{id} reads the session and its peers.

The create response holds session_id, join_code, state, and peers.

Invites

POST /v1/invite sends a short-lived invite to another player by email, tied to a session_id. The recipient sees it in GET /v1/invite and joins with the code. Invites expire on their own.

Signaling

For WebRTC, peers exchange SDP and ICE candidates through POST /v1/game-session/{id}/signals and read them back by polling the same path. This gives you a signaling channel without standing up your own.

Example

curl -s -X POST http://localhost:8080/v1/game-session \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"max_players":4,"public_addr":{"ip":"203.0.113.7","port":7777}}'

Full reference: the /v1/game-session/* and /v1/invite operations.