Skip to main content

​
Session Lifecycle

After successful authentication, the server creates a session identified by sessionId. Sessions have a default lifetime of 24 hours and can be extended by the client. 
Connected → Authenticated → Active → Expiring → Expired
                              ↑         │
                              └─extend──┘

​
Session Expiry

Sessions expire at the expiresAt timestamp returned in the authenticated message. Before expiry, the client can extend the session by sending session_extend. The server responds with session_extended containing the new expiry timestamp. Servers MUST send session_expiring at least 5 minutes before session expiry to give clients time to extend or gracefully disconnect.

​
Inactivity Timeout

Servers MUST enforce an inactivity timeout. If an authenticated client sends no messages for a configurable duration (default: 30 minutes), the server MUST terminate the session. Servers SHOULD send session_expiring before applying the inactivity timeout to give clients an opportunity to send a heartbeat or other message. The timeout duration is a server configuration choice; 30 minutes is the RECOMMENDED default.

​
Reconnection

If a client’s WebSocket connection drops, the client MAY reconnect and resume the session within a reconnection window (default: 120 seconds). See Reconnection for the full flow.

​
State Invariants

  • A session MUST have exactly one active WebSocket connection at any time
  • If a new connection authenticates with the same session, the old connection MUST be terminated
  • Balance state MUST survive session failures — no credits are created or destroyed by a server crash