From 2a633718f18e37c451e5707b28ef1674b1af5aa4 Mon Sep 17 00:00:00 2001 From: "workos-tars[bot]" Date: Mon, 20 Jul 2026 20:30:34 +0000 Subject: [PATCH 1/2] docs: clarify Idempotency-Key is only honored on audit log event creation The WorkOS API only deduplicates requests carrying an Idempotency-Key on POST /audit_logs/events. The README previously implied the key was honored on arbitrary mutations (e.g. organization creation), which could lead callers to retry mutations expecting server-side deduplication that does not happen. Scope the examples and prose to the Audit Logs endpoint and call out the limitation explicitly. --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 3a4660f3..4c84b6a1 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,9 @@ result = client.organizations.list_organizations( ) ``` +> [!NOTE] +> The WorkOS API currently honors `Idempotency-Key` only on the [Create Audit Log Event](https://workos.com/docs/reference/audit-logs/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. + ## 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 models are `@dataclass(slots=True)` classes with `from_dict()` / `to_dict()` for serialization. From e300a81efee9ded8dc6dc95db0de68a249d7ea23 Mon Sep 17 00:00:00 2001 From: Horizon Bot Date: Mon, 20 Jul 2026 21:17:08 +0000 Subject: [PATCH 2/2] docs: fix README inaccuracies found in accuracy audit --- README.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4c84b6a1..633f9bf1 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ See the [API Reference](https://workos.com/docs/reference/client-libraries) for ## Installation +Requires Python 3.10+. + ```bash pip install workos ``` @@ -28,13 +30,13 @@ for org in page.auto_paging_iter(): print(org.name) # Create an organization -org = client.organizations.create_organizations(name="Acme Corp") +org = client.organizations.create_organization(name="Acme Corp") print(org.id) ``` ### Async Client -Every method has an identical async counterpart: +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.) ```python from workos import AsyncWorkOSClient @@ -59,27 +61,35 @@ The client reads credentials from the environment when not passed explicitly: ## Available Resources -The client exposes the full WorkOS API through typed namespace properties: +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.webhooks` | Webhook event verification | -| `client.feature_flags` | Feature flag evaluation | +| `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 @@ -102,7 +112,7 @@ print(page.after) # Cursor for the next page All API errors map to typed exception classes with rich context: ```python -from workos._errors import NotFoundError, RateLimitExceededError +from workos import NotFoundError, RateLimitExceededError try: client.organizations.get_organization("org_nonexistent") @@ -124,9 +134,13 @@ except RateLimitExceededError as e: | `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. + ## Per-Request Options -Every method accepts `request_options` for per-call overrides: +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`): ```python result = client.organizations.list_organizations( @@ -145,7 +159,7 @@ result = client.organizations.list_organizations( ## 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 models are `@dataclass(slots=True)` classes with `from_dict()` / `to_dict()` for serialization. +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