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

[workos-tars]

Summary

The WorkOS API only deduplicates requests carrying an Idempotency-Key header on POST /audit_logs/events (Create Audit Log Event). The README previously presented idempotency keys as a general capability on arbitrary mutations (e.g. organization creation), so a client that retried a mutation with the same key could still create a duplicate — as reported publicly by a user who retried POST /organizations and got two organizations.

Adds a callout under Per-Request Options scoping idempotency_key to audit_logs.create_event.

This README is synced to workos.com/docs SDK pages by the sync-sdk-readmes workflow, so the fix propagates to the public docs on the next sync.

Part of a coordinated docs fix across workos-rust, workos-ruby, workos-python, workos-kotlin, workos-go, and workos-dotnet.

Test plan

Docs-only change; rendered the Markdown and verified the referenced SDK methods exist in this repo.

[greptile-apps]

Greptile Summary

This PR clarifies that the Idempotency-Key header is only honored by the WorkOS API on the POST /audit_logs/events endpoint, preventing users from mistakenly assuming retried mutations (e.g., POST /organizations) are deduplicated. It is part of a coordinated docs fix across multiple WorkOS SDKs.

• Adds a GitHub-flavored [!NOTE] callout under Per-Request Options scoping idempotency_key to audit_logs.create_event and warning that other endpoints do not deduplicate.
• Also corrects a method name typo (create_organizations → create_organization), fixes the error import path to use the public workos namespace, adds Python 3.10+ requirement, expands the Available Resources table with newly introduced namespaces, and adds a Retries section documenting automatic retry/backoff behavior.

Confidence Score: 5/5

Documentation-only change with no production code touched; all updated examples and namespace references verified against current source.

Every factual claim in the README was cross-checked against the codebase: the method name fix (create_organization), the public error import path, the new namespace entries in the resource table, and the async-client qualification all match the source exactly. No logic or runtime behavior is changed.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Documentation-only update: adds idempotency-key scope callout, fixes method name typo, fixes error import path, expands resource table, and adds Retries and Python version sections. All verified against source code.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant SDK as Python SDK
    participant API as WorkOS API

    note over SDK,API: POST /audit_logs/events — idempotency IS honored
    SDK->>API: POST /audit_logs/events (Idempotency-Key: uuid-1)
    API-->>SDK: 200 OK (event created)
    SDK->>API: POST /audit_logs/events (Idempotency-Key: uuid-1) [retry]
    API-->>SDK: 200 OK (deduplicated — same event returned)

    note over SDK,API: POST /organizations — idempotency is NOT honored
    SDK->>API: POST /organizations (Idempotency-Key: uuid-2)
    API-->>SDK: 201 Created (org A)
    SDK->>API: POST /organizations (Idempotency-Key: uuid-2) [retry]
    API-->>SDK: 201 Created (org B — duplicate, key ignored)

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant SDK as Python SDK
    participant API as WorkOS API

    note over SDK,API: POST /audit_logs/events — idempotency IS honored
    SDK->>API: POST /audit_logs/events (Idempotency-Key: uuid-1)
    API-->>SDK: 200 OK (event created)
    SDK->>API: POST /audit_logs/events (Idempotency-Key: uuid-1) [retry]
    API-->>SDK: 200 OK (deduplicated — same event returned)

    note over SDK,API: POST /organizations — idempotency is NOT honored
    SDK->>API: POST /organizations (Idempotency-Key: uuid-2)
    API-->>SDK: 201 Created (org A)
    SDK->>API: POST /organizations (Idempotency-Key: uuid-2) [retry]
    API-->>SDK: 201 Created (org B — duplicate, key ignored)

Loading

_{Reviews (2): Last reviewed commit: "docs: fix README inaccuracies found in a..." | Re-trigger Greptile}

[workos-tars]

Assessed the rest of the README against the codebase per the Slack thread. Fixes pushed in the follow-up commit:

• Quick Start example raised AttributeError: client.organizations.create_organizations → create_organization.
• Resource table was missing 8 accessors (events, organization_domains, organization_membership, groups, client_api, pipes_provider, actions, pkce) while claiming to expose "the full WorkOS API". Added the rows.
• feature_flags described as "evaluation" — the resource only does management/targeting (no evaluate method). Reworded; also webhooks manages endpoints, not just verification.
• "Every method has an identical async counterpart" — local utilities (webhook verification, Actions, PKCE) are sync on both clients. Scoped the claim; same for "every method accepts request_options".
• Undocumented automatic behavior: the SDK retries up to 3 times by default (429/5xx/timeouts, backoff + jitter, Retry-After) and attaches an auto-generated UUID Idempotency-Key to every POST, reused across internal retries. Added a Retries section — directly relevant to this PR's idempotency note.
• Minor: error example now imports from the public workos root instead of the private workos._errors module; added "requires Python 3.10+"; scoped the @dataclass(slots=True) claim to API resource models (pagination wrappers differ).