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

October 1, 2024

v5.4.4

Latest
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)
May 28, 2024

v4.9.0

May 28, 2024

Added

  • Added role to Directory User (https://github.com/workos/workos-python/pull/267)
May 24, 2024

v4.8.0

May 24, 2024

Added

  • Added inviter_user_id to invitation object returned by API (#268)
  • Added new endpoints to the User Management API to support sending your own emails: get_email_verification, get_password_reset, and create_password_reset (#268)
  • Deprecation notice for the send_password_reset_email method in favor of create_password_reset (#268)

Fixed

  • Fixed bug with trailing forward slash in JWKS and logout URLs (#270)
May 17, 2024

v4.7.0

May 17, 2024

What's Changed

  • Add JWKS and logout methods by @PaulAsjes in https://github.com/workos/workos-python/pull/265
  • Add organization membership deactivate and reactivate API methods by @mattgd in https://github.com/workos/workos-python/pull/264

New Contributors

  • @PaulAsjes made their first contribution in https://github.com/workos/workos-python/pull/265

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

May 3, 2024

v4.6.0

May 3, 2024

Added

  • Added accept_invitation_url to invitation object returned by API (#262)
  • Added new endpoints to the Magic Auth API: get_magic_auth and create_magic_auth (#262)
  • Deprecation notice for the send_magic_auth_code method in favor of create_magic_auth (#262)
May 1, 2024

v4.5.0

May 1, 2024

Added

  • Add domain_data to Organizations Create and Update methods to replace the now deprecated domains parameter (#257)
April 29, 2024

v4.4.0

April 29, 2024

What's Changed

  • Allow passing in organization_id into the Events API as a parameter https://github.com/workos/workos-python/pull/259
April 10, 2024

v4.3.1

April 10, 2024

What's Changed

  • Fix string interpolation when building MFA URLs in https://github.com/workos/workos-python/pull/254

Full Changelog: https://github.com/workos/workos-python/compare/v4.3.0...v4.3.1

April 8, 2024

v4.3.0

April 8, 2024

Added

  • Added optional role_slug parameter to send invitation payload to specify a user's organization membership role when inviting (#243)
  • Added password_hash and password_hash_type to User creation (#249)
April 3, 2024

v4.2.0

April 3, 2024
  • Added configurable request timeout
April 2, 2024

v4.1.0

April 2, 2024

Added

  • Added session management api (#245)
March 21, 2024

v4.0.0

March 21, 2024

Added

  • Added impersonator data to User Management authentication responses (#237)

Removed

  • Removed lingering Python 2-related dependencies (#235)
March 18, 2024

v3.1.0

March 18, 2024

Added

  • Role parameter to User Management OrganizationMembership API, and new PUT endpoint for User Management OrganizationMembership API (https://github.com/workos/workos-python/pull/236)