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

January 14, 2025

v5.13.0

Latest
January 14, 2025

Added

  • Added strip_customer_id parameter to update_organization (#401)
  • Added return_to parameter to get_logout_url (#400)

Full Changelog: https://github.com/workos/workos-python/compare/v5.12.1...v5.13.0

January 13, 2025

v5.12.1

January 13, 2025

What's Changed

  • Allows proxies to be properly set via environment variables (#398). If you use the standard HTTP proxy environment variables (e.g. HTTPS_PROXY), it's recommend to verify there's no behavior change in your environment and adjust them if needed.

Full Changelog: https://github.com/workos/workos-python/compare/v5.12.0...v5.12.1

January 7, 2025

v5.12.0

January 7, 2025

Added

  • Support screen_hint in user_management.get_authorization_url by @faroceann in https://github.com/workos/workos-python/pull/396

Full Changelog: https://github.com/workos/workos-python/compare/v5.11.1...v5.12.0

January 6, 2025

v5.11.1

January 6, 2025

What's Changed

  • Update dependency versions pinning (#394)

Full Changelog: https://github.com/workos/workos-python/compare/v5.11.0...v5.11.1

January 2, 2025

v5.11.0

January 2, 2025

What's Changed

  • Add GET /organization/:orgId/roles API support (#392)

Full Changelog: https://github.com/workos/workos-python/compare/v5.10.0...v5.11.0

December 2, 2024

v5.10.0

December 2, 2024

What's Changed

  • Propagate ConflictExceptions properly by @mattgd in https://github.com/workos/workos-python/pull/389
  • Adds session helpers by @PaulAsjes in https://github.com/workos/workos-python/pull/384

Full Changelog: https://github.com/workos/workos-python/compare/v5.9.0...v5.10.0

November 26, 2024

v5.9.0

November 26, 2024

What's Changed

  • Add options to Connection resource and add sso.update_connection() in https://github.com/workos/workos-python/pull/386

Full Changelog: https://github.com/workos/workos-python/compare/v5.8.0...v5.9.0

November 22, 2024

v5.8.0

November 22, 2024

Added

  • Added prompt option to the User Management get_authorization_url method (#383)
November 15, 2024

v5.7.0

November 15, 2024

Added

  • Add widgets module and widget get token API endpoint (#380)
  • Add "Passkey" to AuthenticationMethod (#382)

Full Changelog: https://github.com/workos/workos-python/compare/v5.6.0...v5.7.0

November 6, 2024

v5.6.0

November 6, 2024

What's Changed

  • Add oauth_tokens to AuthkitAuthenticationResponse in https://github.com/workos/workos-python/pull/378

Full Changelog: https://github.com/workos/workos-python/compare/v5.5.1...v5.6.0

October 17, 2024

v5.5.1

October 17, 2024

What's Changed

  • Update pydantic and mypy dependencies #374

Full Changelog: https://github.com/workos/workos-python/compare/v5.5.0...v5.5.1

October 16, 2024

v5.5.0

October 16, 2024

What's Changed

  • Add "role" to profile in https://github.com/workos/workos-python/pull/372

Full Changelog: https://github.com/workos/workos-python/compare/v5.4.4...v5.5.0

October 1, 2024

v5.4.4

October 1, 2024

What's Changed

  • Fix dsync.activated event parsing for Events API when domains present #369

Full Changelog: https://github.com/workos/workos-python/compare/v5.4.3...v5.4.4

September 26, 2024

v5.4.3

September 26, 2024

What's Changed

  • Add missing organization membership webhook events to union #366

Full Changelog: https://github.com/workos/workos-python/compare/v5.4.2...v5.4.3

September 25, 2024

v5.4.2

September 25, 2024

What's Changed

  • Add missing organization membership types to Event type union #363

Full Changelog: https://github.com/workos/workos-python/compare/v5.4.1...v5.4.2

September 10, 2024

v5.4.1

September 10, 2024

What's Changed

  • Fix authentication error payload by @PaulAsjes in https://github.com/workos/workos-python/pull/360

Full Changelog: https://github.com/workos/workos-python/compare/v5.4.0...v5.4.1

September 6, 2024

v5.4.0

September 6, 2024

Added

  • Add domain_verification intent (https://github.com/workos/workos-python/pull/358)
August 26, 2024

v5.3.0

August 26, 2024

Added

  • Added support for authentication.sso_failed and authentication.oauth_failed events (#355)
August 22, 2024

v5.2.0

August 22, 2024

What's changed

  • Added Directory.metadata field providing user and group counts information https://github.com/workos/workos-python/pull/352

Full Changelog: https://github.com/workos/workos-python/compare/v5.1.0...v5.2.0

August 19, 2024

v5.1.0

August 19, 2024

What's changed

  • Added certificate_renewal intent for Admin Portal by @alisherry https://github.com/workos/workos-python/pull/340
August 19, 2024

v5.0.2

August 19, 2024

What's Changed

  • Fix bug for user_management.create_user() and user_management.create_organization_membership() and improve testing (#346)
  • Add missing LiteralOrUntyped wrappers (#344)

Full Changelog: https://github.com/workos/workos-python/compare/v5.0.1...v5.0.2

August 16, 2024

v5.0.1

August 16, 2024

What's Changed

  • Adjust base_url parsing for build_url_with_query_params, which fixes get_authorization_url (#342)

Full Changelog: https://github.com/workos/workos-python/compare/v5.0.0...v5.0.1

August 14, 2024

v5.0.0

August 14, 2024

The v5 release is a major rewrite to add typing and improve consistency across the SDK. There are several breaking changes, which we recommend carefully testing before upgrading the SDK in production.

What’s New

  • Type hints added across the entire SDK to make it safer and easier to integrate WorkOS
  • asyncio support added to several feature modules including Directory Sync, Events, Organizations, SSO, and User Management
  • All API methods return typed models
  • Simplified auto pagination - see details in “breaking changes” section below.
  • Support for multiple clients with different credentials

Breaking Changes & Migration Guide

General

  • To support WorkOS client instantiations with different API keys, client instantiation has been modified:
# Previous client setup
import workos

workos.api_key = "sk_1234"
workos.client_id="client_1234"

# New client instantiation
from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_1234", client_id="client_1234"
)
  • Client ID is now required during instantiation. Your client ID can be found on the API keys page of the WorkOS dashboard.
  • To increase readability of passing arguments to our API methods, all API methods with more than one argument are now required to be passed as keyword arguments:
# Previous usage
workos.client.directory_sync.list_users(
    "directory_123", "group_456", 10
)

# New usage
workos_client.directory_sync.list_users(
    directory_id="directory_123",
    group_id="group_456",
    limit=10
)
  • For all API methods, return values are now objects instead of dictionaries. This means properties are now accessed via dot notation instead of dictionary key indexes. These models can be converted to their dictionary equivalent by calling the .dict() method. See the example below:
# Previous implementation
user = workos.client.user_management.get_user(user_id="user_123")
email = user["email"]

# New implementation
user = workos_client.user_management.get_user(user_id="user_123")
email = user.email

# Alternatively, the user object can be converted to a dictionary
user = workos_client.user_management.get_user(user_id="user_123")
user_dictionary = user.dict()
email = user["email"]
  • Auto pagination now automatically returns the resource entities only and is used implicitly by iterating using a list method, instead of explicitly calling .auto_paging_iter(). For example, to iterate over all SSO connections, you’d do the following:
all_connections = []
for connection in workos_client.sso.list_connections():
    all_connections.append(connection)
  • All unique ID parameters have to be suffixed with _id for clarity, this introduced a number of breaking changes listed in the feature sections below

  • Order for list methods has been removed in favor of the PaginationOrder string literal. Instead of specifying Order.desc or Order.asc, use the literal strings desc and asc, respectively.

API-specific Breaking Changes

Audit Log APIs

  • audit_logs.create_event()
    • organization argument renamed to organization_id
    • If using typing, event is now required to be an AuditLogEvent TypedDict from workos.types.audit_logs
  • audit_logs.create_export()
    • actors argument has been removed. Use actor_names and actor_ids instead.
    • organization argument renamed to organization_id

Directory Sync APIs

  • directory_sync.delete_directory()directory argument renamed to directory_id

  • directory_sync.get_directory()directory argument renamed to directory_id

  • directory_sync.get_group()group argument renamed to group_id

  • directory_sync.get_user()user argument renamed to user_id

  • directory_sync.list_groups()

    • The deprecated version of directory_sync.list_groups() has been removed. directory_sync.list_groups_v2() has been renamed to directory_sync.list_groups().
    • directory argument renamed to directory_id
    • user argument renamed to user_id
  • directory_sync.list_users()

    • The deprecated version of directory_sync.list_users() has been removed. directory_sync.list_users_v2() has been renamed to directory_sync.list_users().
    • directory argument renamed to directory_id
    • group argument renamed to group_id

MFA APIs

  • mfa.verify_factor() has been removed. Use mfa.verify_challenge() instead.

Organizations APIs

  • The deprecated version of organizations.list_organizations() has been removed. organizations.list_organizations_v2() is now organizations.list_organizations().
  • organizations.create_organization() now takes payload contents as separate arguments:
# Previous implementation
organization = workos_client.organizations.create_organization(
    {
        "name": "Foo Corp",
        "domain_data": [
            {
                "domain": "foo-corp.com",
                "state": "pending",
            }
        ],
    }
)

# New implementation
create_organization_payload = {
    "name": "Foo Corp",
    "domain_data": [
        {
            "domain": "foo-corp.com",
            "state": "pending",
        }
    ],
}
organization = workos_client.organizations.create_organization(
    **create_organization_payload
)
  • organizations.delete_organization()organization argument renamed to organization_id
  • organizations.get_organization()organization argument renamed to organization_id
  • organizations.update_organization()organization argument renamed to organization_id

Passwordless APIs

  • passwordless.create_session() now takes payload contents as separate arguments:
# Previous implementation
passwordless_session = workos_client.passwordless.create_session({
    "email": "marcelina@example.com",
    "type": "MagicLink",
})

# New implementation
passwordless_session = workos_client.passwordless.create_session(
    email="marcelina@example.com",
    type="MagicLink",
)
  • passwordless.send_session()id argument renamed to session_id

Portal APIs

  • portal.generate_link()organization argument renamed to organization_id

SSO APIs

  • sso.list_connections()
    • The deprecated version of sso.list_connections() has been removed. sso.list_connections_v2() has been renamed to sso.list_connections().
    • organization argument renamed to organization_id
  • sso.delete_connection()connection argument renamed to connection_id
  • sso.get_authorization_url()
    • domains argument has been removed. Use the organization argument instead.
    • connection argument renamed to connection_id
    • organization argument renamed to organization_id
  • sso.get_connection()connection argument renamed to connection_id
  • sso.get_profile()accessToken argument renamed to access_token

User Management APIs

  • user_management.get_authorization_url()provider argument of type UserManagementProviderType is now a string literal instead of an enum
  • user_management.get_logout_url()session argument renamed to session_id
  • user_management.create_user() now takes payload contents as separate arguments:
# Previous implementation
user = workos_client.user_management.create_user(
    {
        "email": "marcelina@example.com",
        "password": "i8uv6g34kd490s",
        "first_name": "Marcelina",
        "last_name": "Davis",
    }
)

# New implementation
create_user_payload = {
    "email": "marcelina@example.com",
    "password": "i8uv6g34kd490s",
    "first_name": "Marcelina",
    "last_name": "Davis",
}
user = workos_client.user_management.create_user(**create_user_payload)
  • user_management.update_user() now takes payload contents as separate arguments:
# Previous implementation
user = workos_client.user_management.update_user(
    user_id="user_01EHQ7ZGZ2CZVQJGZ5ZJZ1ZJGZ",
    payload={"first_name": "Marcelina", "last_name": "Davis", "email_verified": True},
)

# New implementation
update_user_payload = {
    "first_name": "Marcelina",
    "last_name": "Davis",
    "email_verified": True,
}
user = workos_client.user_management.update_user(
    user_id="user_01EHQ7ZGZ2CZVQJGZ5ZJZ1ZJGZ",
    **update_user_payload,
)
  • user_management.send_password_reset_email() has been removed. Use user_management.create_password_reset() instead.
  • user_management.send_magic_auth_code() has been removed. Use user_management.create_magic_auth() instead.
August 5, 2024

v4.15.0

August 5, 2024

Added

  • Make name optional when updating an organization (#311)
July 30, 2024

v5.0.0beta1

Pre-release
July 30, 2024

What's Changed

This is beta release of the next major version of the WorkOS Python SDK, which adds typing and asyncio support, among other smaller improvements. Full release notes and a migration guide are TBD.

This release contains breaking changes. Exercise caution when utilizing the beta release as it may contain bugs. Changes are not guaranteed to be non-breaking between beta releases.

Full Changelog: https://github.com/workos/workos-python/compare/v4.13.0...v5.0.0-beta1

July 30, 2024

v4.14.0

July 30, 2024

Added

  • Add organization_id parameter to authenticate_with_refresh_token (#296)
July 23, 2024

v4.13.0

July 23, 2024

Added

  • Support for Apple OAuth (https://github.com/workos/workos-python/pull/277)
June 20, 2024

v4.12.0

June 20, 2024

Added

  • Support for lookup_key. Contact support@workos.com for more information (#278)

Deprecated

  • Marked the allow_profiles_outside_organization Organization option as deprecated (#279)
June 12, 2024

v4.11.0

June 12, 2024
  • Add PKCE parameters to User Management authentication methods
June 4, 2024

v4.10.0

June 4, 2024

Added

  • Added support for totp_secret on user_management. enroll_auth_factor (#273)
  • Introduced user_management.find_invitation_by_token method (#274)