---
id: workos
version: "10.2.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# workos — WorkOS Python Client

License: permissive · Maintenance: active · Downloads: 5.7M/mo

## What it is and what it does

WorkOS is a typed Python client for the WorkOS platform, which provides enterprise identity, organization, and authorization infrastructure. It wraps the WorkOS REST API with a namespace-based interface (e.g., client.sso, client.organizations, client.user_management) and supports both synchronous and asynchronous HTTP calls via httpx. The library handles pagination automatically, includes typed exception classes for different HTTP error codes, and ships with full type annotations for IDE support and static type checking.

The client reads credentials from environment variables or explicit parameters, automatically retries requests with exponential backoff on transient failures, and attaches idempotency keys to POST requests. It covers a broad API surface—SSO, user and organization management, directory sync, audit logs, fine-grained authorization (FGA), feature flags, webhooks, MFA, and more—making it suitable for applications that need to integrate WorkOS services without building HTTP calls by hand.

Use it for:

- Integrate WorkOS SSO into a Python web application to authenticate users via SAML, OAuth, or other enterprise protocols.
- Build an admin panel that creates, lists, and manages organizations and their memberships using the organizations and organization_membership namespaces.
- Implement directory sync to pull users and groups from an external directory (LDAP, Active Directory) into your application.
- Set up fine-grained authorization (FGA) to define roles, permissions, and access checks for multi-tenant or complex permission models.
- Verify webhook signatures and process WorkOS events (e.g., user created, organization updated) in your application.
- Generate feature flags and manage targeting rules for A/B testing or gradual feature rollouts.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Python client library for the WorkOS API that provides typed access to identity, organization, directory sync, and authorization services over HTTP.

Yes. The library is actively maintained (release 3 days old), has low install friction, carries no known vulnerabilities, and uses a permissive MIT license. It is well-suited for any Python application integrating WorkOS services. The only constraint is Python 3.10+; if your project targets an older version, you cannot use it.

## Install

pip install workos
uv add workos
poetry add workos

## Installing workos

Before you install: Low install friction with a pure-Python wheel. Actively maintained with a release 3 days old. Requires Python 3.10+. Dependencies are all stable, widely-used libraries (cryptography, httpx, pyjwt, typing-extensions).

License in practice: MIT license is permissive; you can use this library in commercial and proprietary projects with minimal restrictions.

Quickstart:

pip install workos

from workos import WorkOSClient

client = WorkOSClient(api_key="sk_1234", client_id="client_1234")
page = client.organizations.list_organizations()
for org in page.auto_paging_iter():
    print(org.name)

Requires Python 3.10 or later.

Verify before relying:

- Whether the auto-retry behavior (up to 3 times on 429/5xx) and exponential backoff meet your application's resilience needs.
- Whether the 60-second default HTTP timeout is appropriate for your use case or if you'll need per-request overrides.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 5.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

workos api client, identity management sdk, sso single sign-on, organization management api, directory sync integration, user management python, fine-grained authorization, identity-platform, enterprise-auth, async-support

[View on SkillFed](https://skillfed.io/packages/workos) · [View on PyPI](https://pypi.org/project/workos/)