3.3 Session Management
Section 3 — Player Management
3.3 Session Management
Source: AUTHORIZATION_AND_TIMINGS.md (shared — also covers Sections 3, 5.1.6, 10.3)
Token Lifetimes
| Token / Code | Lifetime |
|---|---|
| Player access token | 2 hours |
| SaaS user access token | 2 hours (configurable) |
| Player refresh token | 14 days |
| SaaS user refresh token | 30 days |
| Login session freshness window | 2 hours |
| Email one-time login code | 10 minutes |
| Email verification code | 24 hours |
| Password reset token | 1 hour |
| 2FA challenge window | 5 minutes |
| Impersonation session | 10 minutes |
Refresh Token Rotation
Refresh token rotation is enforced. When a refresh token is used to obtain a new access token:
- A new refresh token is issued.
- The old refresh token is immediately revoked — there is no grace period.
- Attempting to use a revoked refresh token fails.
All tokens in a logical session share a session family ID, so the system can trace the full
rotation chain. Revoked tokens record the reason (e.g., "refresh_rotated", "logout") and
who triggered the revocation.
For tenant-scoped player sessions, the tenant context is preserved across refresh rotations.
Login Session Freshness
Match create and join operations require the player's login session to be fresh — meaning the session's last activity timestamp is within the last 2 hours and the session has not been explicitly ended.
What updates the session's last activity:
- Login and explicit session activity tracking
Token refresh currently rotates access/refresh tokens, but it does not update login session freshness. If a match create/join call requires freshness and the cached login session is stale, the player must re-authenticate.
What makes a session stale:
- No activity for more than 2 hours
- The session was explicitly ended (e.g., logout or timeout event)
If a session is stale or ended, match create and join operations are rejected and the player must re-authenticate.
Logout Behavior
On logout:
- The refresh token is revoked — no new access tokens can be obtained from it.
- The access token is not revoked — it remains valid until its natural 2-hour expiry.
A recently logged-out user's access token can still be used for API calls until it expires. The security boundary is that they cannot refresh, so access is cut off within 2 hours at most.
When Re-auth Is Required
Operations that require a fresh login session (within 2 hours):
- Creating a match
- Joining or rejoining a match
Operations that do NOT require a fresh session:
- Sending match or player events
- Submitting match results
- Ending a match
- Leaving a match
These operations still require both X-Game-Key and a valid player bearer token, and they are
validated by domain state. They do not apply the login session freshness check.