Installation

Command Line
Python

Beta Versions

Certain WorkOS features may be available only in the beta version of the SDK. Beta versions have the -beta.* suffix, for example, 3.2.0-beta.1. For more information on how to use the beta versions, refer to the README in the GitHub repository.

Releases

May 26, 2026

v8.0.0

Latest
May 26, 2026

Bug Fixes

  • deps: update dependency cryptography to v48 (#659) (1ccc411)

  • #662 feat(generated)!: regenerate from spec (10 changes)

    ⚠️ Breaking

    • user_management: Remove organization membership methods, move to new service
      • Removed list_organization_memberships, create_organization_membership, get_organization_membership, update_organization_membership, delete_organization_membership, deactivate_organization_membership, and reactivate_organization_membership methods from UserManagement.
      • Removed RoleSingle and RoleMultiple dataclasses from UserManagement.
      • Organization membership management is now handled by the new OrganizationMembershipService.
      • Client accessor renamed from client.user_management_organization_membership_groups to client.organization_membership.
    • organization_membership: Add new OrganizationMembershipService with membership and group operations
      • Created new OrganizationMembershipService with list_organization_memberships, create_organization_membership, get_organization_membership, update_organization_membership, delete_organization_membership, deactivate_organization_membership, reactivate_organization_membership, and list_organization_membership_groups methods.
      • Added RoleSingle and RoleMultiple dataclasses to support role assignment.
      • Added AsyncOrganizationMembershipService for async operations.
    • vault: Replace hand-maintained Vault module with generated Vault service
      • The old workos.vault module (vault.py) has been replaced by a generated vault/_resource.py service. Method renames:
        • read_objectget_kv
        • read_object_by_nameget_name
        • get_object_metadata → removed (no direct equivalent)
        • list_objectslist_kv
        • list_object_versionslist_kv_versions
        • create_objectcreate_kv
        • update_objectupdate_kv
        • delete_objectdelete_kv
        • create_data_key(key_context=...)create_data_key(context=...)
        • decrypt_data_keycreate_decrypt
      • Removed types: DataKey, DataKeyPair, ObjectDigest, ObjectUpdateBy. Replaced by new generated models (CreateDataKeyResponse, DecryptResponse, ObjectMetadata, ObjectSummary, ObjectWithoutValue, VaultObject, etc.).
      • Added new methods: create_rekey, list_kv_metadata.
      • Added AsyncVault for async operations.
      • Client-side encrypt/decrypt (AES-GCM) methods are preserved with the same signatures.
    • connect: ConnectApplication is now a discriminated union
      • ConnectApplication was a single dataclass; it is now a discriminated union dispatcher based on application_type.
      • All Connect methods (list_applications, create_application, get_application, update_application) now return ConnectApplicationVariant (a union of ConnectApplicationM2M, ConnectApplicationOAuth, or ConnectApplicationUnknown).
      • Code using isinstance(x, ConnectApplication) or accessing type-specific fields without checking the variant will need updating.
    • radar: Remove device_fingerprint and bot_score parameters from assess request
      • Removed device_fingerprint and bot_score optional parameters from Radar.create_attempt and AsyncRadar.create_attempt methods.
      • Removed these fields from RadarStandaloneAssessRequest model.
    • radar: Rename radar list/action enums and remove enum values
      • Renamed RadarAction to RadarListAction and RadarType to RadarListType (affects add_list_entry and remove_list_entry method signatures).
      • RadarStandaloneResponseBlocklistType is now a lazy re-export alias of RadarListType.
      • Removed credential_stuffing and ip_sign_up_rate_limit values from RadarStandaloneResponseControl enum.
      • Removed login, signup, sign_up, and sign_in values from RadarStandaloneAssessRequestAction enum; only sign-up and sign-in remain.
    • authorization: Remove search parameter and add resource/role filtering
      • Removed search parameter from Authorization.list_resources and AsyncAuthorization.list_resources.
      • Added resource_id, resource_external_id, resource_type_slug parameters to list_role_assignments method.
      • Added role_slug parameter to list_role_assignments_for_resource_by_external_id and list_role_assignments_for_resource methods.
    • api_keys: Add expires_at field to API key models
      • Added expires_at optional field to CreateOrganizationApiKey model.
      • Added expires_at optional field to CreateUserApiKey model.
      • Added expires_at to organizational and user API key models (OrganizationApiKey, OrganizationApiKeyWithValue, UserApiKey, UserApiKeyWithValue).
      • Added expires_at parameter to create_organization_api_key and create_user_api_key methods.
    • audit_logs: Rename audit log models and update service references
      • Renamed AuditLogActionJson to AuditLogAction.
      • Renamed AuditLogExportJson to AuditLogExport.
      • Renamed AuditLogSchemaJson to AuditLogSchema.
      • Renamed AuditLogSchemaJsonActor to AuditLogSchemaActorInput and AuditLogSchemaJsonTarget to AuditLogSchemaTargetInput.
      • Added new AuditLogSchemaInput model (used for schema creation payloads).
      • Renamed AuditLogsRetentionJson to AuditLogsRetention.
      • Updated all service methods to use new model names.
    • webhooks: Rename WebhookEndpointJson to WebhookEndpoint
      • Renamed WebhookEndpointJson model to WebhookEndpoint.
      • Updated all service methods to use the new model name.
      • Updated webhook endpoint status references.

    Features

    • common: Add new models for pipes events and enhancements
      • Added Actor model representing the user or API key that performed an action.
      • Added Error model for error response bodies.
      • Added PipeConnectedAccount model with state enumeration.
      • Added pipe event models: PipesConnectedAccountConnected, PipesConnectedAccountDisconnected, PipesConnectedAccountReauthorizationNeeded.
      • Added webhook event enum values for pipes connected account events.
      • Renamed AuditLogExportJsonState to AuditLogExportState.
      • Renamed WebhookEndpointJsonStatus to WebhookEndpointStatus.
      • Updated UserManagementAuthenticationScreenHint to use RadarStandaloneAssessRequestAction type alias.
May 11, 2026

v7.0.1

May 11, 2026

7.0.1 (2026-05-11)

Bug Fixes

  • Harden webhook, vault, session, and base client paths (#654) (d21f3b4)
May 7, 2026

v7.0.0

May 7, 2026

7.0.0 (2026-05-07)

⚠ BREAKING CHANGES

  • api_keys: Restructure API key models for dual ownership
  • common: Add user API key event models and refactor BYOK key provider
  • authorization: Refactor role assignment models and add list endpoints

Features

  • api_keys: Restructure API key models for dual ownership (8b5e91d)
  • authorization: Refactor role assignment models and add list endpoints (8b5e91d)
  • common: Add user API key event models and refactor BYOK key provider (8b5e91d)
  • docs: Publish pdoc-generated API reference to GitHub Pages (#651) (05831ea)
  • user_management: Add user API key management endpoints (8b5e91d)

Bug Fixes

  • generated: Remove service-specific pagination order enums across SDK (8b5e91d)
May 1, 2026

v6.2.0

May 1, 2026

6.2.0 (2026-05-01)

Features

  • add get_jwks_url helper to UserManagement (#644) (53134d3)
  • generated: use explicit re-export form in service init.py (#645) (7ecb2e9)

Bug Fixes

  • set canonical User-Agent header format (#643) (f9cf9a1)
April 28, 2026

v6.1.0

April 28, 2026

6.1.0 (2026-04-28)

Features

  • generated: Add Groups API and Waitlist User events support (#640) (a10d02b)

Bug Fixes

  • Install ruff globally in setup script for code generation (b12b1d3)
April 24, 2026

v6.0.8

April 24, 2026

6.0.8 (2026-04-24)

Bug Fixes

  • list Slack as an auth provider for the authorization URL (#633) (87fc5ab)
April 23, 2026

v6.0.7

April 23, 2026

6.0.7 (2026-04-23)

Bug Fixes

  • export missing types and update event tests (#631) (0bd6cf8)

This PR was generated with Release Please. See documentation.

April 22, 2026

v6.0.6

April 22, 2026

6.0.6 (2026-04-22)

Bug Fixes

  • restore typed EventSchema discriminated union dispatcher (#629) (af95901)
April 20, 2026

v6.0.5

April 20, 2026

6.0.5 (2026-04-20)

Bug Fixes

April 16, 2026

v6.0.4

April 16, 2026

6.0.4 (2026-04-16)

Bug Fixes

  • add documentation on sealing sessions (#625) (5ae90d0)
  • Remove extractVersion from matchUpdateTypes rules (#623) (09a2e5d)
April 15, 2026

v6.0.3

April 15, 2026

6.0.3 (2026-04-15)

Bug Fixes

  • forward Radar context from authenticate_with_code_pkce (#620) (32aea77)
April 14, 2026

v6.0.2

April 14, 2026

6.0.2 (2026-04-14)

Bug Fixes

April 13, 2026

v6.0.1

April 13, 2026

6.0.1 (2026-04-13)

Bug Fixes

April 13, 2026

v6.0.0

April 13, 2026

6.0.0 (2026-04-13)

Top-level notices

  • v6 is a breaking release and now requires Python 3.10 or newer.
  • The SDK now uses generated sync and async clients with top-level imports from workos.
  • client.portal has been renamed to client.admin_portal, and client.fga is not available in v6.

What's changed

  • Rebuilt the Python SDK around a generated client/runtime with updated request handling, pagination, typed models, and error surfaces.
  • Reorganized package exports and service modules to support the new v6 client shape across the SDK.
  • Added release validation coverage, including package smoke tests and the runtime dependency updates needed for packaged installs.

See the V6 migration guide before upgrading from v5.

March 16, 2026

v5.46.0

March 16, 2026

5.46.0 (2026-03-16)

Features

Bug Fixes

  • Allow organization_name to be empty on organization membership events (#595) (865aeb5)
  • deps: update dependency pyjwt to v2.12.0 [security] (#589) (0d50534)
March 9, 2026

v5.45.0

March 9, 2026

5.45.0 (2026-03-09)

Features

  • return organization_name on OrganizationMembership (#574) (dae4dab)

Bug Fixes

  • list_client_secrets returns raw list, not paginated response (#586) (ccc8cd5)
March 9, 2026

v5.44.0

March 9, 2026

5.44.0 (2026-03-06)

Features

  • Add Connect Applications and Client Secrets module (#585) (1ad1623)
  • add cross app auth method (#577) (c67972f)
  • add resource_type_slug to permissions, environment and organization roles (#576) (1004bd7)
  • user-management: add directory_managed to OrganizationMembership (#583) (f0e716e)
March 5, 2026

v5.43.0

March 5, 2026

5.43.0 (2026-03-05)

Features

Bug Fixes

February 20, 2026

v5.42.1

February 20, 2026

What's Changed

  • Fix outdated organization_membership events by @mattgd in #560
  • v5.42.1 by @workos-sdk-automation[bot] in #562

Full Changelog: v5.42.0...v5.42.1

February 17, 2026

v5.42.0

February 17, 2026

What's Changed

  • Add permission and organization role support by @csrbarber in #548
  • feat: Add ability to accept invitations by @gjtorikian in #552
  • v5.42.0 by @workos-sdk-automation[bot] in #553

Full Changelog: v5.41.0...v5.42.0

February 12, 2026

v5.41.0

February 12, 2026

What's Changed

  • chore: Configure Renovate by @renovate[bot] in #527
  • chore(deps): update actions/create-github-app-token action to v2 by @renovate[bot] in #536
  • Bump cryptography from 46.0.3 to 46.0.5 by @dependabot[bot] in #540
  • Add sso subdict to sso auth events by @blackmad-cradle in #542
  • chore(deps): update dependency node to v24 by @renovate[bot] in #539
  • chore(deps): update actions/checkout action to v6 by @renovate[bot] in #535
  • Add missing event types by @blackmad-cradle in #543
  • Add API Keys support (create, list, delete) by @blackmad-cradle in #544
  • v5.41.0 by @workos-sdk-automation[bot] in #547

New Contributors

  • @renovate[bot] made their first contribution in #527
  • @dependabot[bot] made their first contribution in #540

Full Changelog: v5.40.1...v5.41.0

February 4, 2026

v5.40.1

February 4, 2026

What's Changed

  • Add custom_attributes field to OrganizationMembership by @ajworkos in #524
  • Add accepted_user_id to invitation by @gjtorikian in #525
  • v5.40.1 by @workos-sdk-automation[bot] in #526

Full Changelog: v5.40.0...v5.40.1

January 22, 2026

v5.40.0

January 22, 2026

What's Changed

  • ci: Migrate release workflow to Trusted Publishing by @birdcar in #517
  • Implement the remaining Audit Logs functionality by @birdcar in #515
  • Use correct var/secret names by @gjtorikian in #522
  • v5.40.0 by @workos-sdk-automation[bot] in #523

New Contributors

  • @workos-sdk-automation[bot] made their first contribution in #523

Full Changelog: v5.39.1...v5.40.0

January 20, 2026

v5.39.1

January 20, 2026

What's Changed

  • Allow for same param name but different contextual usage by @gjtorikian in #520
  • Bump to 5.39.1 by @gjtorikian in #521

Full Changelog: v5.39.0...5.39.1

January 15, 2026

v5.39.0

January 15, 2026

What's Changed

  • Add context7.json to repo by @nicknisi in #504
  • Add read_object_by_name method for Vault API by @hexedpackets in #506
  • Add Python SDK support for WorkOS Pipes by @birdcar in #507
  • Bump version to v5.38.0 by @birdcar in #509
  • Add new supported password hash types by @alastair in #461
  • Move from setup.py to uv+pyproject.toml by @birdcar in #496
  • Remove unused pypi environment for now by @birdcar in #513
  • Correct params for list_groups and list_users by @gjtorikian in #512
  • Release 5.38.1 by @birdcar in #514
  • Add nox and nox-uv for DX testing improvements by @birdcar in #516
  • v5.39.0 by @nicknisi in #518

New Contributors

  • @hexedpackets made their first contribution in #506
  • @birdcar made their first contribution in #507
  • @alastair made their first contribution in #461
  • @gjtorikian made their first contribution in #512

Full Changelog: v5.37.0...v5.39.0

January 13, 2026

v5.38.1

January 13, 2026

What's Changed

  • Add new supported password hash types by @alastair in #461
  • Move from setup.py to uv+pyproject.toml by @birdcar in #496
  • Correct params for list_groups and list_users by @gjtorikian in #512
  • Add Support for a JWT Leeway Parameter by @Th3R3p0 in #430

New Contributors

  • @Th3R3p0 made their first contribution in #430
  • @alastair made their first contribution in #461

Full Changelog: v5.38.0...v5.38.1

January 12, 2026

v5.38.0

January 12, 2026

What's Changed

  • Add context7.json to repo by @nicknisi in #504
  • Add read_object_by_name method for Vault API by @hexedpackets in #506
  • Add Python SDK support for WorkOS Pipes by @birdcar in #507

Full Changelog: v5.37.0...v5.38.0

December 17, 2025

v5.37.0

December 17, 2025

What's Changed

  • Add support for list user feature flags endpoint by @stanleyphu in #502
  • v5.37.0 by @stanleyphu in #503

Full Changelog: v5.36.0...v5.37.0

December 16, 2025

v5.36.0

December 16, 2025

What's Changed

  • adding "session.revoke" to events type by @rarevalo13 in #500
  • v5.36.0 by @rarevalo13 in #501

Full Changelog: v5.35.0...v5.36.0

December 5, 2025

v5.35.0

December 5, 2025

What's Changed

  • Expose api key validation by @denizs in #491

New Contributors

  • @denizs made their first contribution in #491

Full Changelog: v5.34.1...v5.35.0