Install & Compatibility
Where this runs
tested against v10.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.852s · 47.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 1.732s · 48MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
workos
✓ import workos
This is the primary way to configure and interact with the WorkOS API by setting global configuration variables (e.g., `workos.api_key`, `workos.client_id`) and accessing sub-modules (e.g., `workos.sso`).
WorkOSClient
✓ from workos import WorkOSClient
Use `WorkOSClient` to instantiate an explicit client object, which is useful for multi-tenant applications or when managing multiple WorkOS configurations within a single application.
WebhookSignatureError
✓ from workos.errors import WebhookSignatureError
Specific error class for handling webhook signature verification failures.
This quickstart demonstrates how to configure the WorkOS Python Client using environment variables for API keys and client IDs. It then shows examples of listing organizations, generating an SSO authorization URL, and verifying a webhook event. Remember to replace placeholder API keys, client IDs, domains, and redirect URIs with your actual WorkOS credentials and configurations. Webhook verification is critical and requires a valid signature and secret.
import os
import workos
from pprint import pprint
# Configure WorkOS using environment variables
# For local testing, replace with actual test keys if env vars are not set
workos.api_key = os.environ.get("WORKOS_API_KEY", "sk_test_YOUR_API_KEY")
workos.client_id = os.environ.get("WORKOS_CLIENT_ID", "client_test_YOUR_CLIENT_ID")
# Optional: Set the API base URL for custom environments (e.g., local development)
# workos.base_api_url = "http://localhost:8000/"
# Example 1: List organizations
try:
print("\n--- Listing Organizations ---")
organizations = workos.organizations.list_organizations(limit=5)
if organizations.data:
for org in organizations.data:
pprint(org.to_dict())
else:
print("No organizations found.")
except Exception as e:
print(f"Error listing organizations: {e}")
# Example 2: Generate an SSO authorization URL
try:
print("\n--- Generating SSO Authorization URL ---")
authorization_url = workos.sso.get_authorization_url(
domain="example.com", # Replace with a domain configured in WorkOS
redirect_uri="http://localhost:8000/callback", # Must be a valid redirect URI configured in WorkOS
state="some-secure-random-state"
)
print(f"SSO Authorization URL for example.com: {authorization_url}")
except Exception as e:
print(f"Error generating SSO URL: {e}")
# Example 3: Verify a webhook event (simulated payload)
try:
print("\n--- Simulating Webhook Verification ---")
# In a real scenario, payload and signature_header come from the HTTP request
webhook_payload = '{"id": "wh_01G827B6V8F1PZ1D7E40P5940X", "event": "directory_sync.user.created", "data": {}}'
webhook_signature = "t=1678886400,v1=signature_hash"
webhook_secret = os.environ.get("WORKOS_WEBHOOK_SECRET", "webhook_secret_YOUR_WEBHOOK_SECRET")
# This will likely fail with a dummy signature, but demonstrates the call
print("Attempting to verify webhook (will likely fail with dummy data)...")
event = workos.webhooks.verify_event(
payload=webhook_payload,
signature_header=webhook_signature,
secret=webhook_secret
)
print(f"Webhook event verified: {event['event']}")
except workos.errors.WebhookSignatureError as e:
print(f"Webhook signature verification failed: {e}")
except Exception as e:
print(f"Error during webhook verification simulation: {e}")
Debug
Known issues
breakingMajor breaking changes were introduced in version `2.0.0`. This included significant renames (e.g., `WorkOS` class methods moved to top-level `workos` module), changes in error handling (e.g., `workos.exceptions` moved to `workos.errors`), and parameter name updates across various API methods. Upgrading from `1.x.x` to `2.x.x` requires code modifications.fixConsult the official WorkOS Python SDK v2.0.0 migration guide. Update import paths, module access patterns, and parameter names according to the new API structure.
affects: <2.0.0 to 2.x.x+
gotchaWebhook events must always be cryptographically verified using `workos.webhooks.verify_event()`. Failure to do so exposes your webhook endpoints to spoofing and unauthorized access, posing a significant security risk.fixEnsure that every incoming webhook payload is passed to `workos.webhooks.verify_event()` along with the `WorkOS-Signature` header and your webhook secret. Catch `workos.errors.WebhookSignatureError` to handle invalid signatures gracefully.
affects: All
gotchaMany WorkOS list endpoints (e.g., `list_organizations`, `list_users`) are paginated. If you don't explicitly handle pagination by iterating through `organizations.list_organizations(limit=N, after='cursor')` or similar patterns, you will only receive the first page of results, leading to incomplete data.fixWhen fetching lists of resources, check the `list_response.list_metadata.after` field. If present, make subsequent calls with `after=list_response.list_metadata.after` until `after` is `None`.
affects: All
gotchaThe global configuration pattern (`import workos; workos.api_key = ...`) can lead to issues in complex applications (e.g., multi-tenant services, tests) where different WorkOS configurations are needed simultaneously. All requests will use the globally set credentials.fixFor explicit control over client instances and their configurations, use `from workos import WorkOSClient` and instantiate client objects: `client = WorkOSClient(api_key="...", client_id="...")`. Pass this `client` object around or create new ones as needed.
affects: All
Upgrade
Version history
10.2.0latest on PyPI · released Aug 11, 2026
Audit
Dependencies
No dependency data recorded yet.