3.1 Player Authentication & Login

Summary

Covers the ways a game client can sign a player in through Gamers Lab. This includes Steam, Epic, Sequence, EVM wallet login, email one-time codes, and Mock login for development. It focuses on game and tenant authentication flows, not email/password or global player portal login.

In most flows, your game sends a provider credential and its X-Game-Key to the API. Gamers Lab validates the credential, finds or creates the player account, and returns access and refresh tokens for that tenant. Some login types use the shared /login endpoint, while wallet and email one-time code login use their own two-step flows.

Actors

These are the main parties involved in a player login. In practice, your game client usually just needs the right game key and the player's provider credential.

• Game client: holds the X-Game-Key; calls login endpoints on behalf of the player.
• Gamers Lab API: validates provider credentials, resolves player identity, issues JWT tokens.
• External provider (Steam / Epic): validates the ticket/token presented by the game client.
• Player: the end user; never interacts with the API directly.

Providers

Gamers Lab provides several ways to authenticate users from within your game. Out of the box, it supports the providers listed below.

Login Types

Below, each login type explains the credentials needed and which endpoint flow to use. Steam, Epic, Sequence, and Mock use the shared login endpoint, while wallet and email login use dedicated multi-step flows.

Shared Login Endpoint

Use this endpoint when your game already has a Steam, Epic, Sequence, or Mock credential for the player. Gamers Lab validates that credential and returns player tokens for the tenant tied to X-Game-Key.

POST /api/player-auth/login
X-Game-Key: <game_auth_key>
Content-Type: application/json

Request body (Steam, Epic, Sequence, Mock):

{
  "provider": "Steam",
  "token": "<provider_token>",
  "createAccountIfMissing": true,
  "profileVisibility": "limited",
  "deviceInfo": { ... }
}

profileVisibility is optional and is only applied when this request creates a brand-new player. Valid values are private, limited, and full. If omitted, the new account defaults to limited. If the player already exists, the field is ignored and the stored visibility is left unchanged.

Response (200 OK):

{
  "accessToken": "<jwt>",
  "refreshToken": "<token>",
  "tokenType": "Bearer",
  "expiresIn": 7200,
  "playerId": "<uuid>",
  "isNewPlayer": false,
  "tenantId": "<uuid>",
  "sessionId": "<uuid>"
}

EmailOneTimeCode does not use this shared endpoint. Use the tenant-scoped email OTC endpoints below.

Token Lifecycle

Access tokens are meant to be short-lived. Refresh tokens let the client get a new token pair, and logout revokes the refresh token for the current session.

• Access tokens are short-lived JWTs with auth_type=player and scope=player.
• Refresh tokens are long-lived and rotate on every use (old token invalidated on refresh).
• POST /api/player-auth/refresh — exchanges a refresh token for a new access + refresh token pair.
• POST /api/player-auth/logout — revokes the refresh token and records the session-end event. The access token remains valid until expiry. Requires sessionId; optionally accepts deviceId for session correlation.

Player Lookup

Use this when your game server only needs to check whether a player already exists for a provider identity. It is a lookup only; it does not log the player in or create an account.

POST /api/player-auth/players/exists
X-Game-Key: <game_auth_key>
Content-Type: application/json

Request body:

{
  "provider": "Steam",
  "providerUserId": "<steamId>"
}

Returns 200 + \{ "playerId": "<uuid>" \} if found; 404 otherwise. Supported provider values for the flows covered here: Steam, Epic, Sequence, EvmWallet, EmailOneTimeCode, and Mock. For EmailOneTimeCode, use the normalized email address as providerUserId; lookup only succeeds when the email credential is verified and the player already has tenant access.

Account Creation

Gamers Lab can create a player account during login when the request allows it. New accounts default to limited profile visibility unless you provide another valid visibility setting.

• /login with createAccountIfMissing: true (default): creates a new player if none exists.
• /login with createAccountIfMissing: false: returns 404 when the player does not exist.
• POST /api/player-auth/players (explicit create): hard-fails with 409 if the player already exists. Supports Steam, Epic, Sequence, and Mock.
• POST /api/player-auth/email/otc: creates a pending email OTC player account if none exists; the first successful /otc/exchange marks the email credential verified.
• New player creation routes can optionally accept profileVisibility with values private, limited, or full.
• If profileVisibility is omitted during creation, the account defaults to limited.
• If a create-capable login request targets an already-existing player, any provided profileVisibility value is ignored.

Error Semantics

These are the common errors your game client should expect from player auth endpoints. A 401 usually means the credential or game key could not be accepted, while 403 means the player is known but cannot access that tenant.

Tenant Game Auth Endpoints

Applies to:

• POST /api/player-auth/login
• POST /api/player-auth/players
• POST /api/player-auth/players/exists
• POST /api/player-auth/challenge
• POST /api/player-auth/challenge/verify
• POST /api/player-auth/email/otc
• POST /api/player-auth/otc/exchange
• POST /api/player-auth/wallet/challenge
• POST /api/player-auth/wallet/verify

Assertion JWT Endpoints

Applies to:

• POST /api/player-auth/jwt/exchange
• POST /api/player-auth/jwt/validate