Add userManagement.listSessions (#1316)

## Description

This endpoint will list the active sessions for a given user.

## Documentation

```
[X] Yes
```

If yes, link a related docs PR and add a docs maintainer as a reviewer.
Their approval is required.

<!-- av pr metadata
This information is embedded by the av CLI when creating PRs to track
the status of stacks when using Aviator. Please do not delete or edit
this section of the PR.
```
{"parent":"main","parentHead":"","trunk":"main"}
```
-->

Author: cmatheson

src/user-management/fixtures/list-sessions.json

@@ -0,0 +1,22 @@
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "session",
+      "id": "session_01K0T5TNC755C7FGRQFJRS4QK5",
+      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
+      "ip_address": "192.168.65.1",
+      "user_id": "user_01K0T5T62NBSETXQD3NVGEA2RN",
+      "auth_method": "oauth",
+      "status": "active",
+      "expires_at": "2026-07-22T22:59:48.743Z",
+      "ended_at": null,
+      "created_at": "2025-07-23T04:59:48.738Z",
+      "updated_at": "2025-07-23T04:59:48.738Z"
+    }
+  ],
+  "list_metadata": {
+    "before": null,
+    "after": null
+  }
+}

src/user-management/interfaces/index.ts

@@ -25,6 +25,7 @@ export * from './invitation.interface';
 export * from './list-auth-factors-options.interface';
 export * from './list-invitations-options.interface';
 export * from './list-organization-memberships-options.interface';
+export * from './list-sessions-options.interface';
 export * from './list-users-options.interface';
 export * from './magic-auth.interface';
 export * from './oauth-tokens.interface';

src/user-management/interfaces/list-sessions-options.interface.ts

@@ -0,0 +1,7 @@
+import { PaginationOptions } from '../../common/interfaces/pagination-options.interface';
+
+// tslint:disable-next-line:no-empty-interface
+export interface ListSessionsOptions extends PaginationOptions {}
+
+// tslint:disable-next-line:no-empty-interface
+export interface SerializedListSessionsOptions extends PaginationOptions {}

src/user-management/interfaces/session.interface.ts

@@ -1,5 +1,18 @@
 import { Impersonator } from './impersonator.interface';
 
+export type AuthMethod =
+  | 'external_auth'
+  | 'impersonation'
+  | 'magic_code'
+  | 'migrated_session'
+  | 'oauth'
+  | 'passkey'
+  | 'password'
+  | 'sso'
+  | 'unknown';
+
+export type SessionStatus = 'active' | 'expired' | 'revoked';
+
 export interface Session {
   object: 'session';
   id: string;
@@ -8,6 +21,12 @@ export interface Session {
   userAgent: string | null;
   organizationId?: string;
   impersonator?: Impersonator;
+  authMethod: AuthMethod;
+  status: SessionStatus;
+  expiresAt: string;
+  endedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
 }
 
 export interface SessionResponse {
@@ -18,4 +37,10 @@ export interface SessionResponse {
   user_agent: string | null;
   organization_id?: string;
   impersonator?: Impersonator;
+  auth_method: AuthMethod;
+  status: SessionStatus;
+  expires_at: string;
+  ended_at: string | null;
+  created_at: string;
+  updated_at: string;
 }

src/user-management/serializers/index.ts

@@ -12,10 +12,12 @@ export * from './email-verification.serializer';
 export * from './enroll-auth-factor-options.serializer';
 export * from './factor.serializer';
 export * from './invitation.serializer';
+export * from './list-sessions-options.serializer';
 export * from './magic-auth.serializer';
 export * from './password-reset.serializer';
 export * from './reset-password-options.serializer';
 export * from './send-password-reset-email.serializer';
+export * from './session.serializer';
 export * from './create-user-options.serializer';
 export * from './send-magic-auth-code-options.serializer';
 export * from './update-user-options.serializer';

src/user-management/serializers/list-sessions-options.serializer.ts

@@ -0,0 +1,10 @@
+import {
+  ListSessionsOptions,
+  SerializedListSessionsOptions,
+} from '../interfaces/list-sessions-options.interface';
+
+export const serializeListSessionsOptions = (
+  options: ListSessionsOptions,
+): SerializedListSessionsOptions => ({
+  ...options,
+});

src/user-management/serializers/session.serializer.ts

@@ -8,4 +8,10 @@ export const deserializeSession = (session: SessionResponse): Session => ({
   userAgent: session.user_agent,
   organizationId: session.organization_id,
   impersonator: session.impersonator,
+  authMethod: session.auth_method,
+  status: session.status,
+  expiresAt: session.expires_at,
+  endedAt: session.ended_at,
+  createdAt: session.created_at,
+  updatedAt: session.updated_at,
 });

src/user-management/session.spec.ts

@@ -1,5 +1,5 @@
 import { WorkOS } from '../workos';
-import { Session } from './session';
+import { CookieSession } from './session';
 import * as jose from 'jose';
 import { sealData } from 'iron-session';
 import userFixture from './fixtures/user.json';
@@ -33,7 +33,7 @@ describe('Session', () => {
         cookiePassword: 'cookiePassword',
       });
 
-      expect(session).toBeInstanceOf(Session);
+      expect(session).toBeInstanceOf(CookieSession);
     });
   });
 

src/user-management/session.ts

@@ -18,7 +18,7 @@ type RefreshOptions = {
   organizationId?: string;
 };
 
-export class Session {
+export class CookieSession {
   private jwks: ReturnType<typeof createRemoteJWKSet> | undefined;
   private userManagement: UserManagement;
   private ironSessionProvider: IronSessionProvider;

src/user-management/user-management.spec.ts

@@ -12,6 +12,7 @@ import invitationFixture from './fixtures/invitation.json';
 import listFactorFixture from './fixtures/list-factors.json';
 import listInvitationsFixture from './fixtures/list-invitations.json';
 import listOrganizationMembershipsFixture from './fixtures/list-organization-memberships.json';
+import listSessionsFixture from './fixtures/list-sessions.json';
 import listUsersFixture from './fixtures/list-users.json';
 import magicAuthFixture from './fixtures/magic_auth.json';
 import organizationMembershipFixture from './fixtures/organization-membership.json';
@@ -1537,6 +1538,40 @@ describe('UserManagement', () => {
     });
   });
 
+  describe('listSessions', () => {
+    it('sends a listSessions request', async () => {
+      fetchOnce(listSessionsFixture);
+
+      const resp = await workos.userManagement.listSessions(userId);
+
+      expect(fetchURL()).toContain(`/user_management/users/${userId}/sessions`);
+
+      expect(resp).toMatchObject({
+        object: 'list',
+        data: [
+          {
+            object: 'session',
+            id: 'session_01K0T5TNC755C7FGRQFJRS4QK5',
+            userId: 'user_01K0T5T62NBSETXQD3NVGEA2RN',
+            userAgent:
+              'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36',
+            ipAddress: '192.168.65.1',
+            authMethod: 'oauth',
+            status: 'active',
+            expiresAt: '2026-07-22T22:59:48.743Z',
+            endedAt: null,
+            createdAt: '2025-07-23T04:59:48.738Z',
+            updatedAt: '2025-07-23T04:59:48.738Z',
+          },
+        ],
+        listMetadata: {
+          before: null,
+          after: null,
+        },
+      });
+    });
+  });
+
   describe('deleteUser', () => {
     it('sends a deleteUser request', async () => {
       fetchOnce();