Authentication Events¶

Authentication events cover the connection-level login and logout lifecycle. In the current server build, authentication is performed entirely during the WebSocket handshake (see authentication.md); the in-band auth.login and auth.logout messages are part of the documented contract and are planned for a future protocol version.

Reference: authentication.md · connection.md · protocol.md

Event list¶

auth.login¶

Description¶

Initiates authentication on an existing (unauthenticated or reconnecting) connection by presenting a valid access token in-band. Today the server performs the equivalent work during the handshake and never opens an unauthenticated socket, so this event is planned. When implemented, it will allow re-authenticating a connection without reconnecting, and will return the same SocketUser identity the handshake would have produced.

Direction¶

Client → Server

Roles Allowed¶

All roles.

Permissions Required¶

None at the event level (the presented token's role defines the permission set).

Request Schema¶

Response Schema¶

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "auth.login",
  "data": {
    "authenticated": true,
    "userId": "sub_01HQ5BWYP1Y5RX0W5X0W5X0W5X",
    "role": "SUBSCRIBER"
  }
}

Error Responses¶

Validation Rules¶

Example Request¶

{
  "type": "auth.login",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJzdWJfMDFIUTVCWFdZUCIsInJvbGUiOiJTVUJTQ1JJQkVSIiwidHlwZSI6ImFjY2VzcyIsImV4cCI6MTc1NDE2NjQwMH0.signature"
  }
}

Example Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "auth.login",
  "data": {
    "authenticated": true,
    "userId": "sub_01HQ5BWYP1Y5RX0W5X0W5X0W5X",
    "role": "SUBSCRIBER"
  }
}

Broadcast Behaviour¶

None. auth.login affects only the sending connection.

Related Events¶

• auth.logout
• events/system.md — system.ping pre-flight before login.

Notes¶

• Implementation status: Planned. Today login = successful handshake; a failed handshake closes the socket with code 1008.
• When implemented, the permission set of the connection will be replaced by the token's role-derived permissions.

Best Practices¶

• Prefer the handshake authentication documented in authentication.md. Do not rely on auth.login until the protocol version that introduces it is released.
• Re-authenticate by reconnecting with a fresh token; never reuse an expired token.

auth.logout¶

Description¶

Terminates the authenticated session on the connection. In the current build, clients close the socket (optionally after calling the REST logout endpoint) to end the session; the server then releases rooms, subscriptions, presence, and the connection. auth.logout is planned as an in-band equivalent that would close the session without relying on transport closure.

Direction¶

Client → Server

Roles Allowed¶

All roles.

Permissions Required¶

None.

Request Schema¶

Response Schema¶

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "auth.logout",
  "data": {
    "loggedOut": true
  }
}

Error Responses¶

Validation Rules¶

Example Request¶

{
  "type": "auth.logout",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "data": {}
}

Example Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "auth.logout",
  "data": {
    "loggedOut": true
  }
}

Broadcast Behaviour¶

None, except that other connections of the same user are unaffected. Presence for the leaving connection is removed (see events/presence.md).

Related Events¶

• auth.login
• events/presence.md — presence.left after logout.
• lifecycle.md — disconnect cleanup.

Notes¶

• Implementation status: Planned. Today logout = client closes the socket (close code 1000) and, if desired, calls the REST logout endpoint to revoke the token.

Best Practices¶

• Close the socket cleanly with code 1000 after logout so the server can release resources promptly.
• Do not reuse a logged-out connection; open a fresh one for the next session.