The WorkOS library for Python provides convenient access to the WorkOS API from applications written in Python, hosted on PyPI.
See the API Reference for Python usage examples.
Requires Python 3.10+.
pip install workosfromworkosimportWorkOSClientclient=WorkOSClient(api_key="sk_1234", client_id="client_1234")
# List organizationspage=client.organizations.list_organizations()
fororginpage.auto_paging_iter():
print(org.name)
# Create an organizationorg=client.organizations.create_organization(name="Acme Corp")
print(org.id)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.)
fromworkosimportAsyncWorkOSClientasync_client=AsyncWorkOSClient(api_key="sk_1234", client_id="client_1234")
page=awaitasync_client.organizations.list_organizations()
asyncfororginpage.auto_paging_iter():
print(org.name)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) |
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 |
Paginated endpoints return SyncPage[T] (or AsyncPage[T]) with built-in auto-pagination:
# Iterate through all pages automaticallyforuserinclient.user_management.list_users().auto_paging_iter():
print(user.email)
# Or work with a single pagepage=client.user_management.list_users(limit=10)
print(page.data) # List of items on this pageprint(page.has_more()) # Whether more pages existprint(page.after) # Cursor for the next pageAll API errors map to typed exception classes with rich context:
fromworkosimportNotFoundError, RateLimitExceededErrortry:
client.organizations.get_organization("org_nonexistent")
exceptNotFoundErrorase:
print(f"Not found: {e.message}")
print(f"Request ID: {e.request_id}")
exceptRateLimitExceededErrorase:
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 |
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.
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/",
}
)Note
The WorkOS API currently honors Idempotency-Key only on the Create Audit Log Event endpoint (audit_logs.create_event). Other endpoints accept the header but do not deduplicate requests, so a retried mutation elsewhere can still create a duplicate.
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.
WorkOS follows Semantic Versioning. Breaking changes are only released in major versions. We strongly recommend reading changelogs before making major version upgrades.
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.