Session Endpoints Index

Session Management

This API supports multi-session authentication, allowing users to be logged in from multiple devices simultaneously. The session management endpoints provide users with visibility and control over their active sessions.

How Session Management Works

  1. Users can have multiple concurrent sessions (default: up to 5 sessions per user)
  2. Each session is tied to a specific device/browser combination
  3. Sessions are tracked with device information (IP address, user agent, device identifier)
  4. Users can view all their active sessions and see which one is currently being used
  5. Users can selectively revoke individual sessions or revoke all other sessions for security
  6. When the session limit is reached, older sessions are automatically cleaned up based on the configured strategy

Session Configuration:

Security Considerations

Best Practices

  • Regular Session Review: Users should periodically review their active sessions and revoke any unrecognized sessions
  • Compromise Response: If a user suspects their account is compromised, they should use the "revoke others" endpoint to immediately terminate all other sessions
  • Device Management: Users should log out from devices they no longer use or have access to
  • Session Limits: The configurable session limits prevent unlimited session accumulation and potential abuse

Automatic Cleanup

The system automatically manages sessions through:

  • Expiration: Sessions automatically expire based on their configured lifetime
  • Limit Enforcement: When the session limit is exceeded, older sessions are automatically revoked
  • Cleanup Strategy: Configurable cleanup removes sessions based on creation time or last access time

Session Endpoints

GET /api/auth/sessions

Get all active sessions for the current user (requires authentication)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Response (200 OK):

{
    "sessions": [
        {
            "id": 1,
            "deviceIdentifier": "Chrome-MacOS-12345",
            "ipAddress": "192.168.1.100",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
            "createdAt": "2023-12-01T10:30:00Z",
            "lastAccessedAt": "2023-12-01T14:45:00Z",
            "isCurrent": true
        },
        {
            "id": 2,
            "deviceIdentifier": "Safari-iPhone-67890",
            "ipAddress": "192.168.1.101",
            "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15",
            "createdAt": "2023-11-30T08:15:00Z",
            "lastAccessedAt": "2023-11-30T18:20:00Z",
            "isCurrent": false
        }
    ],
    "maxSessions": 5,
    "multipleSessionsEnabled": true
}

Notes:

  • Does not require CSRF token as it's a GET request
  • The isCurrent field indicates which session corresponds to the current request
  • maxSessions is returned as a number, not a string
  • deviceIdentifier, ipAddress, and userAgent may be null if not captured during session creation
POST /api/auth/sessions/revoke-others

Revoke all other sessions except the current one. This is useful when a user suspects their account has been compromised and wants to log out all other devices while keeping their current session active.

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Response (200 OK):

{
    "message": "Successfully revoked 3 other sessions",
    "revokedCount": 3
}

Error Responses:

{
    "message": "No authentication token provided"
}

{
    "message": "Invalid session"
}

Notes:

  • Does not require CSRF token - session endpoints are excluded from CSRF protection in auth routes
  • The current session (determined by the Authorization header) is never revoked
  • Returns the count of sessions that were actually revoked
DELETE /api/auth/sessions/:sessionId

Revoke a specific session by ID. Users can only revoke their own sessions.

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

URL Parameters:

sessionId: The ID of the session to revoke (integer)

Response (200 OK):

{
    "message": "Session revoked successfully"
}

Error Responses:

{
    "message": "Session not found"
}

{
    "message": "Failed to revoke session"
}

Notes:

  • Does not require CSRF token - session endpoints are excluded from CSRF protection in auth routes
  • Users can only revoke sessions that belong to their account
  • The session is verified to belong to the authenticated user before revocation
  • Successfully revoking a session will invalidate any tokens associated with that session