WorkOS Python Library
The WorkOS library for Python provides convenient access to the WorkOS API from applications written in Python, hosted on PyPI.
Documentation
See the API Reference for Python usage examples.
Installation
Requires Python 3.10+.
pip install workos
Quick Start
from workos import WorkOSClient
client = WorkOSClient(api_key="sk_1234", client_id="client_1234")
# List organizations
page = client.organizations.list_organizations()
for org in page.auto_paging_iter():
print(org.name)
# Create an organization
org = client.organizations.create_organization(name="Acme Corp")
print(org.id)
Async Client
Every HTTP API method has an identical async counterpart on AsyncWorkOSClient. (Pure-local utilities such as webhook signature verification, Actions helpers, and PKCE are synchronous on both clients.)
from workos import AsyncWorkOSClient
async_client = AsyncWorkOSClient(api_key="sk_1234", client_id="client_1234")
page = await async_client.organizations.list_organizations()
async for org in page.auto_paging_iter():
print(org.name)
Environment Variables
The client reads credentials from the environment when not passed explicitly:
| Variable | Description |
|---|---|
WORKOS_API_KEY |
WorkOS API key |
WORKOS_CLIENT_ID |
WorkOS client ID |
WORKOS_BASE_URL |
Override the API base URL (defaults to https://api.workos.com/) |
WORKOS_REQUEST_TIMEOUT |
HTTP timeout in seconds (defaults to 60) |
WORKOS_ISSUER |
Expected iss claim of session access tokens, comma-separated to accept several (not validated when unset; also settable via jwt_issuer=) |
Available Resources
The client exposes the WorkOS API through typed namespace properties:
| Property | Description |
|---|---|
client.sso |
Single Sign-On connections and authorization |
client.organizations |
Organization management |
client.organization_domains |
Organization domain verification |
client.organization_membership |
Organization membership management |
client.user_management |
Users, identities, auth methods, invitations |
client.directory_sync |
Directory connections and directory users/groups |
client.groups |
Organization group management |
client.admin_portal |
Admin Portal link generation |
client.audit_logs |
Audit log events, exports, and schemas |
client.authorization |
Fine-Grained Authorization (FGA) resources, roles, permissions, and checks |
client.events |
Events API |
client.webhooks |
Webhook endpoint management and event verification |
client.feature_flags |
Feature flag management (list, enable/disable, targeting) |
client.api_keys |
Organization API key management |
client.client_api |
Client API token generation |
client.connect |
OAuth application management |
client.widgets |
Widget session tokens |
client.multi_factor_auth |
MFA enrollment and verification (also available as client.mfa) |
client.pipes |
Data Integrations |
client.pipes_provider |
Organization data integration configuration |
client.radar |
Radar risk scoring |
client.passwordless |
Passwordless authentication sessions |
client.vault |
Encrypted data vault |
client.actions |
AuthKit Actions signature verification and response signing |
client.pkce |
PKCE code verifier/challenge helpers |
Pagination
Paginated endpoints return SyncPage[T] (or AsyncPage[T]) with built-in auto-pagination:
# Iterate through all pages automatically
for user in client.user_management.list_users().auto_paging_iter():
print(user.email)
# Or work with a single page
page = client.user_management.list_users(limit=10)
print(page.data) # List of items on this page
print(page.has_more()) # Whether more pages exist
print(page.after) # Cursor for the next page
Error Handling
All API errors map to typed exception classes with rich context:
from workos import NotFoundError, RateLimitExceededError
try:
client.organizations.get_organization("org_nonexistent")
except NotFoundError as e:
print(f"Not found: {e.message}")
print(f"Request ID: {e.request_id}")
except RateLimitExceededError as e:
print(f"Retry after: {e.retry_after} seconds")
| Exception | Status Code |
|---|---|
BadRequestError |
400 |
AuthenticationError |
401 |
AuthorizationError |
403 |
NotFoundError |
404 |
ConflictError |
409 |
UnprocessableEntityError |
422 |
RateLimitExceededError |
429 |
ServerError |
5xx |
Retries
The client automatically retries requests up to 3 times (configurable via the max_retries request option) on 429 and 5xx responses, timeouts, and connection errors, using exponential backoff with jitter and honoring Retry-After. The SDK attaches an auto-generated Idempotency-Key (UUID v4) to every POST request and reuses the same key across its internal retries.
HTTP Backends
The SDK sends requests through httpx2 by default. Pass your own configured client as http_client to control proxies, TLS, connection limits, or transports:
import httpx2
from workos import AsyncWorkOSClient, WorkOSClient
client = WorkOSClient(
api_key="sk_...",
http_client=httpx2.Client(proxy="http://proxy.internal:3128", verify="/etc/ssl/corp.pem"),
)
async_client = AsyncWorkOSClient(
api_key="sk_...",
http_client=httpx2.AsyncClient(limits=httpx2.Limits(max_connections=20)),
)
httpx 0.28 clients are accepted as well; the two libraries share an API. The SDK closes only clients it created. A client you pass in stays open after client.close(), so close it yourself when you are done with it.
Custom backends
Any object implementing workos.HTTPBackend (or workos.AsyncHTTPBackend for the async client) can be passed as http_client. The SDK hands the backend a fully built URL, the final headers, an optional bytes body, and a timeout in seconds, and expects a workos.HTTPResponse back. Raise workos.TransportTimeout, workos.TransportConnectError, or workos.TransportError for network failures so the SDK's retry logic can handle them. The headers mapping on the response must be case-insensitive.
The following aiohttp adapter is an example, not a supported part of the SDK:
import asyncio
import aiohttp
import yarl
from workos import (
AsyncWorkOSClient,
HTTPResponse,
TransportConnectError,
TransportError,
TransportTimeout,
)
class AiohttpBackend:
def __init__(self, session: aiohttp.ClientSession) -> None:
self._session = session
async def request(self, method, url, *, headers, content, timeout) -> HTTPResponse:
try:
async with self._session.request(
method,
yarl.URL(url, encoded=True), # keep the SDK's percent-encoding intact
headers=headers,
data=content,
timeout=aiohttp.ClientTimeout(total=timeout),
allow_redirects=True,
) as resp:
body = await resp.read()
return HTTPResponse(resp.status, resp.headers, body, method, str(resp.url))
except (asyncio.TimeoutError, aiohttp.ServerTimeoutError) as exc: # before connection errors
raise TransportTimeout(str(exc)) from exc
except aiohttp.ClientConnectionError as exc:
raise TransportConnectError(str(exc)) from exc
except aiohttp.ClientError as exc:
raise TransportError(str(exc)) from exc
async def close(self) -> None:
await self._session.close()
async def main() -> None:
async with aiohttp.ClientSession() as session:
client = AsyncWorkOSClient(api_key="sk_...", http_client=AiohttpBackend(session))
page = await client.organizations.list_organizations()
Per-Request Options
Every API method accepts request_options for per-call overrides (local helpers such as webhook/Actions signature verification and PKCE utilities do not make HTTP calls and don't take request_options):
result = client.organizations.list_organizations(
request_options={
"timeout": 10,
"max_retries": 5,
"extra_headers": {"X-Custom": "value"},
"idempotency_key": "my-key",
"base_url": "https://staging.workos.com/",
}
)
Type Safety
This SDK ships with full type annotations (py.typed / PEP 561) and works with mypy, pyright, and IDE autocompletion out of the box. All API resource models are @dataclass(slots=True) classes with from_dict() / to_dict() for serialization.
SDK Versioning
WorkOS follows Semantic Versioning. Breaking changes are only released in major versions. We strongly recommend reading changelogs before making major version upgrades.
Beta Releases
WorkOS has features in Beta that can be accessed via Beta releases. We would love for you to try these and share feedback with us before these features reach general availability (GA). To install a Beta version, please follow the installation steps above using the Beta release version.
Note: there can be breaking changes between Beta versions. We recommend pinning the package version to a specific version.
More Information
1 maintainer
Release files for workos 10.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| workos-10.4.0.tar.gz | 285.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| workos-10.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size:1.1 MB
Release files / workos-10.4.0.tar.gz
| Download URL | workos-10.4.0.tar.gz |
|---|---|
| Size | 285.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
51833f0006a096562d1a11eb0dc1be330f437311793e16faac86a6d2a3f13cd8
|
|
BLAKE2b-256 checksum How to use checksums |
7ce078f17586f7bc55c8f61d108f3eb74bf84cbbb74416232e04ebacb0440cef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / workos-10.4.0-py3-none-any.whl
| Download URL | workos-10.4.0-py3-none-any.whl |
|---|---|
| Size | 794.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ad7396fb091675a6f10b0bfb1118074d7229c88ae82c9c88c6b752f284ef9881
|
|
BLAKE2b-256 checksum How to use checksums |
4d1d6dbb6d39cd9d378f60814add9641d6840e93e5ccc5c5302da682301db441
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
