Connect 4 — Create a session

Sessions are created server-side using your secret API key. The response contains a short-lived JWT sessionToken that is safe to pass to the client.

Endpoint

POSThttps://api.beta-gamer.com/v1/sessions

Request

const res = await fetch('https://api.beta-gamer.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bg_live_xxxx',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    game:      'connect4',
    matchType: 'matchmaking',
    players:   [{ id: 'user_123', displayName: 'Alex' }],
  }),
});

const { sessionToken, sessionId } = await res.json();

Body parameters

Parameter	Type	Required	Default	Description
`game`	"connect4"	Yes	—	Must be "connect4".
`matchType`	"matchmaking" \| "bot" \| "private"	Yes	—	How the match is created.
`players`	Player[]	Yes	—	{ id, displayName }[]. id is your tenant's userId — appears in game:over.winner.
`botDifficulty`	"easy" \| "medium" \| "hard"	No	"medium"	Bot strength. Only applies when matchType is "bot".

matchType details

matchmaking

Player is queued and paired with the next available opponent. Pass one player.

{ game: 'connect4', matchType: 'matchmaking', players: [{ id: 'u1', displayName: 'Alex' }] }

bot

Player is immediately matched against an AI. Pass one player.

{ game: 'connect4', matchType: 'bot', botDifficulty: 'hard', players: [{ id: 'u1', displayName: 'Alex' }] }

private

A private room is created. Pass two players — both connect to the same room.

{ game: 'connect4', matchType: 'private', players: [{ id: 'u1', displayName: 'Alex' }, { id: 'u2', displayName: 'Sam' }] }

Ended sessions

const res = await fetch(`/api/v1/sessions/validate?token=${sessionToken}`);
const { status, result } = await res.json();

if (status === 'ended') {
  // show final result — result: { winner, reason }
} else {
  // render BetaGamerProvider
}

userId vs displayName

players[].id is your tenant's user ID — this is what game:over.winner contains. Always compare winner against players[0].id, never against displayName.

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