Skip to content

docs: clarify Idempotency-Key is only honored on audit log event creation #692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gjtorikian merged 2 commits into from
Jul 21, 2026
Merged

docs: clarify Idempotency-Key is only honored on audit log event creation #692

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a63371
docs: clarify Idempotency-Key is only honored on audit log event crea…
workos-tars[bot] Jul 20, 2026
e300a81
docs: fix README inaccuracies found in accuracy audit
Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 25 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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")
Expand All @@ -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(
Expand All @@ -140,9 +154,12 @@ 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.
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

Expand Down
Loading