Checkers — Create a session

Sessions are created server-side using your secret API key. Never call this from the browser. 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:              'checkers',
    matchType:         'matchmaking',
    players:           [{ id: 'user_123', displayName: 'Alex' }],
    afkTimeoutEnabled: true,
  }),
});

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

Body parameters

Parameter	Type	Required	Default	Description
`game`	"checkers"	Yes	—	Must be "checkers".
`matchType`	"matchmaking" \| "bot"	Yes	—	How the match is created. Private matches are not yet supported for checkers.
`players`	Player[]	Yes	—	{ id, displayName }[]. id is your tenant's userId — it appears in game:over.winner for result identification. displayName is shown in the UI. One entry for matchmaking/bot.
`botDifficulty`	"easy" \| "medium" \| "hard"	No	"medium"	Bot strength. Only applies when matchType is "bot".
`afkTimeoutEnabled`	boolean	No	true	Whether the 90-second AFK forfeit rule is active.
`theme`	ThemeOverride	No	—	Override dashboard theme tokens for this session only.

matchType details

matchmaking

Player is placed in a queue. The server pairs them with the next available opponent. Pass one player.

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

bot

Player is immediately matched against an AI. Use botDifficulty to set strength. Pass one player.

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

Response

Field	Type	Description
`sessionId`	string	Unique session identifier. Store server-side to look up results later.
`sessionToken`	string	Short-lived JWT. Pass to the client as the token prop on BetaGamerProvider.
`expiresAt`	string	ISO 8601 timestamp. Token is valid until this time (typically 1 hour).

{
  "sessionId":    "sess_01j9abc123",
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "expiresAt":    "2026-03-16T02:00:00.000Z"
}

Ended sessions

Validate the token before rendering the game UI to handle page refreshes after a game ends:

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

if (status === 'ended') {
  // result: { winner, reason, duration }
  // show final result screen
} 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. Display names can change; user IDs are stable identifiers you control.

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