Add list sessions and revoke session methods and tests

[awolfden]

Description

Adds User Management Sessions APIs to the WorkOS Python SDK, following existing patterns (typed models, RequestHelper, WorkOSListResource pagination, sync/async clients), without breaking changes.

What’s included

• New typed model
  • workos/types/user_management/session.py: Session
• New list filters and resource typing
  • workos/types/user_management/list_filters.py: SessionsListFilters
  • SessionsListResource = WorkOSListResource[Session, SessionsListFilters, ListMetadata]
• New public APIs (sync + async) in workos/user_management.py
  • List Sessions (user-scoped)
    • Sync:
      • def list_sessions(self, *, user_id: str, limit: Optional[int] = None, before: Optional[str] = None, after: Optional[str] = None, order: Optional[PaginationOrder] = None) -> SessionsListResource
    • Async:
      • async def list_sessions(self, *, user_id: str, limit: Optional[int] = None, before: Optional[str] = None, after: Optional[str] = None, order: Optional[PaginationOrder] = None) -> SessionsListResource
    • HTTP: GET user_management/users/{user_id}/sessions
• Revoke Session
  • Sync:
    • def revoke_session(self, *, session_id: str) -> Session
  • Async:
    • async def revoke_session(self, *, session_id: str) -> Session
  • HTTP: POST user_management/sessions/revoke with JSON {"session_id": "..."}

Pagination behavior

• Mirrors existing patterns (e.g., list_auth_factors):
• Accepts limit, before, after, order (Literal["asc","desc"])
• Uses WorkOSListResource + ListPage for standard list metadata and auto-pagination
• Includes user_id in list_args so auto-pagination preserves path filters
• Omits None query params

Tests

• tests/test_user_management_list_sessions.py
• Verifies request path, query serialization, response parsing, list metadata
• Auto-pagination (sync + async)
• tests/test_user_management_revoke_session.py
• Verifies POST body and Session parsing (sync + async)
• All existing tests remain passing

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[X] Yes

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

[greptile-apps]

Greptile Overview

Summary

This PR adds User Management Sessions APIs to the WorkOS Python SDK with two new methods: list_sessions (user-scoped session listing) and revoke_session (session revocation).

Key Changes:

• New Session Pydantic model with proper typing for all session attributes (id, user_id, organization_id, status, auth_method, ip_address, user_agent, expires_at, ended_at, timestamps)
• list_sessions method with full pagination support (limit, before, after, order) and auto-pagination via WorkOSListResource
• revoke_session method using POST with JSON body {"session_id": "..."}
• Both methods implemented for sync (UserManagement) and async (AsyncUserManagement) clients
• Comprehensive test coverage using @pytest.mark.sync_and_async decorator
• Session model exported in public API (workos/__init__.py)

Implementation Quality:

• Follows existing SDK patterns consistently (matches list_auth_factors pattern exactly)
• Proper type annotations throughout with Pydantic validation
• Includes user_id in list_args for correct auto-pagination behavior
• Tests verify request path, query params, JSON body, and response parsing
• No breaking changes to existing APIs

Confidence Score: 5/5

• This PR is safe to merge with no identified issues
• The implementation precisely follows established SDK patterns, includes comprehensive test coverage, maintains type safety throughout, and introduces no breaking changes. All code mirrors existing similar features (especially list_auth_factors), demonstrating consistency with the codebase architecture.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
workos/types/user_management/session.py	5/5	Added new Session model with proper Pydantic typing, following existing SDK patterns
workos/user_management.py	5/5	Implemented list_sessions and revoke_session methods for both sync and async clients, following existing patterns
tests/test_user_management_list_sessions.py	5/5	Comprehensive tests for list_sessions including query params, parsing, and auto-pagination
tests/test_user_management_revoke_session.py	5/5	Complete test coverage for revoke_session verifying POST request, JSON body, and response parsing

Sequence Diagram

sequenceDiagram
    participant Client
    participant UserManagement
    participant HTTPClient
    participant WorkOSAPI

    Note over Client,WorkOSAPI: List Sessions Flow
    Client->>UserManagement: list_sessions(user_id="user_123", limit=10)
    UserManagement->>UserManagement: Build params with limit, before, after, order
    UserManagement->>HTTPClient: request(GET, /user_management/users/{user_id}/sessions, params)
    HTTPClient->>WorkOSAPI: GET /user_management/users/user_123/sessions?limit=10
    WorkOSAPI-->>HTTPClient: Response with session list + metadata
    HTTPClient-->>UserManagement: Parse response
    UserManagement->>UserManagement: Create SessionsListResource with list_args (includes user_id)
    UserManagement-->>Client: Return SessionsListResource (supports auto-pagination)

    Note over Client,WorkOSAPI: Revoke Session Flow
    Client->>UserManagement: revoke_session(session_id="session_abc")
    UserManagement->>UserManagement: Build JSON payload {"session_id": "session_abc"}
    UserManagement->>HTTPClient: request(POST, /user_management/sessions/revoke, json)
    HTTPClient->>WorkOSAPI: POST /user_management/sessions/revoke
    WorkOSAPI-->>HTTPClient: Response with revoked Session object
    HTTPClient-->>UserManagement: Parse response
    UserManagement->>UserManagement: Validate as Session model
    UserManagement-->>Client: Return Session with status="revoked"

Loading

_{8 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[mattgd]

Looks good - thanks for adding!