2.2 Sessions & Device Registration

Both the session ledger and device tracking live entirely inside Game/Sessions/.

Player login appends a row to the session ledger and creates/updates mutable session state for runtime freshness checks. Devices are registered at login time as a side effect of the auth flow.

Session Event Types

GamePlatform Enum

The platform field on sessions and stored device rows uses the GamePlatform enum. Unknown exists as a fallback/default value.

Nintendo

PlayStation

Xbox

PC

Mobile

VR

Cloud / Other

2.2.1 Device Registration

What Device Registration Is

When a player logs into a game, the game client can optionally submit a DeviceInfoRequest alongside its authentication payload. The server uses this to maintain a record of which physical devices have accessed the game under each player account.

Registration is upsert-based: if a device with the same fingerprint already exists for the player, it is updated. If not, a new record is created. The player never calls a registration endpoint directly — it happens as a side effect of login.

When It Runs

Triggered during every login flow where deviceInfo is included. Runs after authentication succeeds and before the player JWT is issued.

Login flows that support device registration:

• POST /api/player-auth/login (Steam, Epic, Sequence, Mock)
• POST /api/player-auth/email/signup
• POST /api/player-auth/email/tenant-login
• POST /api/player-auth/otc/exchange
• POST /api/player-auth/wallet/verify (EVM wallet)

Providing deviceInfo is optional. If omitted, login proceeds normally and the session row is created with device_id = null.

Blocked Device Check

Before registration completes, the service checks whether the fingerprint matches a device with is_blocked = true. If so, the login is rejected — the player cannot authenticate from a blocked device regardless of auth provider.

ClientInfoRequest

DeviceInfoRequest

DeviceName is not part of registration. Players assign a display name later via PATCH /api/player/devices/{deviceId}.

Upsert Behaviour

first_seen_at is set only on creation and never updated.

What Gets Stored

Table: game_player_devices

Once registered, the device id is linked to the session row in game_app_player_login_sessions.device_id.

Device Data Model — Full Schema

Table: game_player_devices (mutable)

Code References

• Service interface: GamersLabRestAPI/Game/Sessions/Services/IPlayerDeviceService.cs
  • GetOrCreateDeviceAsync — registration entry point
  • IsDeviceBlockedAsync — blocked check at login
  • RecordDeviceLoginAsync — updates last seen / login count
• Service implementation: GamersLabRestAPI/Game/Sessions/Services/PlayerDeviceService.cs
• Repository: GamersLabRestAPI/Game/Sessions/Repositories/PlayerDeviceRepository.cs
• Device model: GamersLabRestAPI/Game/Sessions/Models/PlayerDevice.cs
• Device management DTOs: GamersLabRestAPI/Game/Sessions/DTOs/PlayerDeviceDTOs.cs
• Login telemetry DTOs: GamersLabRestAPI.Contracts/Game/Sessions/DTOs/DeviceInfoRequest.cs
• Platform enum: GamersLabRestAPI.Contracts/Game/Sessions/Models/GamePlatform.cs

2.2.2 Session Ledger

What the Session Ledger Is

Current implemented session ledger rows are login and logout-style events. Token refresh has a service method and enum value, but POST /api/player-auth/refresh does not currently call it. Nothing in the ledger is ever updated or deleted. It is the authoritative historical record of persisted player auth activity.

The ledger is separate from the mutable session state (game_player_login_session_state), which tracks only current status. The ledger is for history and audit; the state table is for runtime checks.

Two Ledger Tables

Session events are split across two tables by direction:

Both carry the same session_id — the link connecting a login row to its logout row. A single logical session can produce a login row and, if explicitly closed, a logout row.

Session ID

session_id is the logical identifier for one player auth session, shared across all ledger rows that belong to it:

Login event        → game_app_player_login_sessions  (session_id = X)
Logout event       → game_app_player_logout_sessions (session_id = X)

session_id is also the PK of the session state row in game_player_login_session_state. All three tables are joined by it.

Event Types and Which Table They Write To

Login Ledger — game_app_player_login_sessions

Append-only. Composite PK: (tenant_id, id).

auth_provider is stored denormalised so that queries by provider name do not require a join.

Logout Ledger — game_app_player_logout_sessions

Append-only. Composite PK: (tenant_id, id).

Logout Reasons

Three Timestamps

Both ledger tables carry three timestamps following the platform's ledger conventions:

All three are immutable once written. received_at_db is used as the cursor in paginated history queries.

Row Hash

row_hash is an application-computed hash of the row's content, written at insert time. Provides a deduplication fingerprint and an integrity check.

Query Surfaces

Player Session History — cursor-paginated log of login events for a specific player.

SessionHistoryQuery:

SessionHistoryResponse:

sessions[]
  id                  Guid
  sessionId           Guid
  tenantId            Guid
  authProvider        string
  platform            string
  platformDisplayName string
  deviceId            Guid?
  clientVersion       string?
  clientBuild         string?
  ipAddress           string?
  occurredAt          DateTime
totalCount            int
pageSize              int
hasMore               bool
nextCursorTimestamp   DateTime?
nextCursorId          Guid?

Tenant Session Analytics — aggregate view across all sessions for a tenant.

SessionAnalyticsResponse:

totalLogins           int
totalLogouts          int
uniquePlatforms       int
uniquePlayers         int
loginsByPlatform      Dictionary<string, int>
loginsByProvider      Dictionary<string, int>

Player Session Summary — high-level lifetime summary for a single player across all tenants.

PlayerSessionSummaryResponse:

totalLogins           int
totalGamesPlayed      int         — distinct tenant count
platformsUsed         string[]
firstLoginAt          DateTime?
lastLoginAt           DateTime?
recentSessions[]
  tenantId            Guid
  platform            string
  platformDisplayName string
  clientVersion       string?
  loginAt             DateTime

Relationship to Session State

A login writes a new ledger row and creates the state row. A logout writes a logout ledger row and sets ended_at on the state row. Token refresh currently rotates tokens only; it does not write a ledger row or update last_seen_at.

Code References

• Login session model: GamersLabRestAPI/Game/Sessions/Models/PlayerLoginSession.cs
• Logout session model: GamersLabRestAPI/Game/Sessions/Models/PlayerLogoutSession.cs
• Session state model: GamersLabRestAPI/Game/Sessions/Models/PlayerLoginSessionState.cs
• Session event types: GamersLabRestAPI/Game/Sessions/Models/SessionEventType.cs
• Session service: GamersLabRestAPI/Game/Sessions/Services/PlayerSessionService.cs
  • LogLoginAsync, LogLogoutAsync, LogTokenRefreshAsync, LogSessionExpiredAsync, LogForceLogoutAsync
  • Current refresh endpoint does not call LogTokenRefreshAsync
  • GetPlayerSessionHistoryAsync, GetTenantSessionHistoryAsync, GetTenantAnalyticsAsync, GetPlayerSessionSummaryAsync
• Session DTOs: GamersLabRestAPI/Game/Sessions/DTOs/PlayerSessionDTOs.cs
• Session repository: GamersLabRestAPI/Game/Sessions/Repositories/NpgsqlPlayerSessionRepository.cs

2.2.3 Session Heartbeat

What a Player Session Is

When a player authenticates, two things are created:

1. An append-only ledger row (game_app_player_login_sessions) recording the login event permanently.
2. A mutable session state row (game_player_login_session_state) tracking whether the session is currently active and when it was last seen.

Logout and force-expiry service methods operate on the state row. The ledger row is never modified. The current refresh endpoint does not update the session state row.

Session Lifetime

A player session has an inactivity window of 2 hours.

The clock is measured from last_seen_at, not from started_at. A session active for 8 hours is still valid as long as last_seen_at is within the last 2 hours.

Session is considered expired when either:

• ended_at is set (explicit logout or server-terminated), or
• last_seen_at < now − 2 hours (inactivity timeout)

Note: is_active on the session state model is defined as ended_at == null. A session can satisfy is_active = true and still be expired by the 2-hour TTL check.

Heartbeat — How Sessions Stay Alive

There is no dedicated heartbeat endpoint. Although LogTokenRefreshAsync can update last_seen_at, the current refresh endpoint does not call it.

If the cached session state is older than 2 hours, the player must re-authenticate before session-sensitive writes can succeed.

Expiry Detection — Lazy, Not Scheduled

There is no background service that auto-expires sessions. Expiry is detected lazily the next time a session-sensitive write is attempted.

When expiry is detected:

• Create-match returns per-player 410 Gone validation errors.
• Join currently maps the same expired-session validation to 409 Conflict.
• The current match validation path does not append a SessionExpired logout row or set ended_at.

Until that lazy check triggers, an expired session row sits with ended_at = null and a stale last_seen_at.

What Checks Session Validity

Not all write operations care whether a player session is active.

Player JWT operations — verify the JWT signature and expiry. The JWT has a 2-hour TTL.

Game write operations (X-Game-Key + bearer token) — session validity only checked where semantically meaningful:

A player must have an active session to be accepted into a match. Once in, the match can progress and conclude — and all associated events and results can be written — even if that player's session later expires mid-game. A network disruption or client crash should not invalidate in-progress match data.

Session State Data Model

Table: game_player_login_session_state (mutable)

Known Limitations

Active session count / concurrent session policy (TODO): There is currently no enforcement of a maximum concurrent session count per player. A player can log in from multiple devices and maintain multiple active sessions simultaneously. A future per-tenant policy could enforce single-session mode or a maximum count.

Proactive expiry (TODO): Expired sessions are not closed automatically. No background service scans for sessions where last_seen_at < now - 2 hours and sets ended_at. Current match validation also does not close the session on expiry. This means:

• Session analytics may count sessions as "active" past their actual expiry time
• ended_at is null for sessions that expired without explicit logout

Code References

• Session state model: GamersLabRestAPI/Game/Sessions/Models/PlayerLoginSessionState.cs
• Session service: GamersLabRestAPI/Game/Sessions/Services/PlayerSessionService.cs
  • LogTokenRefreshAsync — can update last_seen_at, but is not called by the refresh endpoint
  • LogSessionExpiredAsync — can write a timeout logout event, but is not called by match validation
  • LogLogoutAsync — writes user_logout event
• Session repository: GamersLabRestAPI/Game/Sessions/Repositories/NpgsqlPlayerSessionRepository.cs
  • UpdateLastSeenAsync — session-state freshness update helper
  • EndSessionAsync — sets ended_at
• Match session validation: GamersLabRestAPI/Game/Matches/Services/MatchService.cs
  • LoginSessionTtl constant — TimeSpan.FromHours(2)
  • ValidateMatchPlayer — applies session cutoff check; returns 410 if expired
• Player login/refresh controller: GamersLabRestAPI/PlayerAuth/Controllers/PlayerLoginController.cs