Session Management

CORTEX tracks user sessions to provide visibility into active logins and enable session termination.

Session Model

Each login creates a session record containing:

Field	Description
id	Unique session identifier
userId	User who owns the session
createdAt	When the session was created
lastActiveAt	Last activity timestamp
ipAddress	Client IP address
userAgent	Browser/client identifier
expiresAt	When the session expires

List Active Sessions

View all active sessions for the current user.

Endpoint

GET /auth/sessions

Response (200 OK)

{
  "data": [
    {
      "id": "ses_abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "lastActiveAt": "2024-01-15T14:45:00.000Z",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "expiresAt": "2024-01-22T10:30:00.000Z",
      "current": true
    },
    {
      "id": "ses_def456",
      "createdAt": "2024-01-14T08:00:00.000Z",
      "lastActiveAt": "2024-01-14T12:30:00.000Z",
      "ipAddress": "10.0.0.50",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)...",
      "expiresAt": "2024-01-21T08:00:00.000Z",
      "current": false
    }
  ]
}

The current field indicates which session belongs to the current request.

Terminate a Session

Users can terminate any of their sessions (logout remotely).

Endpoint

DELETE /auth/sessions/:sessionId

Response (204 No Content)

No response body on success.

Error Responses

404 Not Found

{
  "type": "https://api.cortex.purplelab.ai/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Session not found",
  "instance": "/auth/sessions/ses_invalid"
}

caution

Terminating the current session is equivalent to logging out. You will need to log in again.

Code Examples

List Sessions (TypeScript)

interface Session {
  id: string;
  createdAt: string;
  lastActiveAt: string;
  ipAddress: string;
  userAgent: string;
  expiresAt: string;
  current: boolean;
}

async function listSessions(accessToken: string): Promise<Session[]> {
  const response = await fetch('http://localhost:8091/auth/sessions', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  });

  if (!response.ok) {
    throw new Error('Failed to fetch sessions');
  }

  const data = await response.json();
  return data.data;
}

// Usage
const sessions = await listSessions(accessToken);
sessions.forEach(session => {
  console.log(`${session.id}: ${session.ipAddress} ${session.current ? '(current)' : ''}`);
});

Terminate Session (TypeScript)

async function terminateSession(
  accessToken: string,
  sessionId: string
): Promise<void> {
  const response = await fetch(
    `http://localhost:8091/auth/sessions/${sessionId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail);
  }
}

// Usage: Terminate all sessions except current
const sessions = await listSessions(accessToken);
for (const session of sessions) {
  if (!session.current) {
    await terminateSession(accessToken, session.id);
    console.log(`Terminated session: ${session.id}`);
  }
}

cURL Examples

# List sessions
curl http://localhost:8091/auth/sessions \
  -H "Authorization: Bearer <access-token>"

# Terminate a session
curl -X DELETE http://localhost:8091/auth/sessions/ses_abc123 \
  -H "Authorization: Bearer <access-token>"

Session Expiration

Sessions expire based on the refresh token lifetime (7 days by default). When a session expires:

1. The refresh token becomes invalid
2. The session is automatically cleaned up
3. The user must log in again

Security Features

Concurrent Session Limits

Tenants can configure maximum concurrent sessions per user. When exceeded, the oldest session is automatically terminated.

Session Activity Tracking

The lastActiveAt timestamp is updated on each authenticated request, providing an activity timeline.

Device Information

The userAgent field helps users identify which device/browser created each session, making it easier to detect unauthorized access.

Best Practices

1. Review sessions regularly: Check for unfamiliar devices or locations
2. Terminate unused sessions: Remove sessions you no longer need
3. Log out when done: Don't leave sessions active on shared computers
4. Monitor for anomalies: Unusual login patterns may indicate compromise