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.

Removes the idempotency_key from the generic per-request options example and adds a callout scoping the header 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 tightens the README documentation in three areas: it scopes Idempotency-Key deduplication to the audit_logs.create_event endpoint (removing the misleading generic example that implied other mutations were deduplicated), corrects the configuration section to note that environment variables must be passed explicitly (the SDK does not auto-read them), and rounds out the error-handling snippet with a WorkOS::APIConnectionError rescue clause.

• Idempotency-Key callout: request_options[:idempotency_key] is removed from the generic per-request example and a NOTE admonition is added explaining that only POST /audit_logs/events honors the header for deduplication.
• Configuration clarification: The previous shell-env example (WORKOS_API_KEY=... ruby app.rb) is removed; the new text correctly states the SDK requires explicit configuration via WorkOS.configure, consistent with what lib/workos/configuration.rb actually does.
• Minor additions: provider: "authkit" is added to the PKCE example and WorkOS::APIConnectionError rescue is added to the error-handling snippet.

Confidence Score: 5/5

Docs-only change with no runtime code modifications; safe to merge.

All changes are confined to README.md. The three factual claims introduced — that the SDK requires explicit configuration (confirmed in configuration.rb), that idempotency deduplication is scoped to the audit log event endpoint, and the updated error-handling class names — are consistent with the actual library source. No logic, tests, or library files are touched.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Docs-only update: clarifies idempotency key scope to audit log events, removes misleading env-var auto-read claim, adds provider param to PKCE example, and expands error handling section.

Sequence Diagram

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

    Note over App,API: Idempotency-Key behavior (clarified in this PR)

    App->>SDK: "audit_logs.create_event(..., request_options: {idempotency_key: "key-123"})"
    SDK->>API: POST /audit_logs/events Idempotency-Key: key-123
    API-->>SDK: 200 OK (deduplicated if key seen before)
    SDK-->>App: response

    App->>SDK: "organizations.create_organization(..., request_options: {idempotency_key: "key-456"})"
    SDK->>API: POST /organizations Idempotency-Key: key-456
    API-->>SDK: 201 Created (header accepted but NOT deduplicated)
    SDK-->>App: response
    Note over API: Duplicate may be created on retry!

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 App
    participant SDK as WorkOS Ruby SDK
    participant API as WorkOS API

    Note over App,API: Idempotency-Key behavior (clarified in this PR)

    App->>SDK: "audit_logs.create_event(..., request_options: {idempotency_key: "key-123"})"
    SDK->>API: POST /audit_logs/events Idempotency-Key: key-123
    API-->>SDK: 200 OK (deduplicated if key seen before)
    SDK-->>App: response

    App->>SDK: "organizations.create_organization(..., request_options: {idempotency_key: "key-456"})"
    SDK->>API: POST /organizations Idempotency-Key: key-456
    API-->>SDK: 201 Created (header accepted but NOT deduplicated)
    SDK-->>App: response
    Note over API: Duplicate may be created on retry!

Loading

_{Reviews (3): Last reviewed commit: "Update installation instructions in READ..." | 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:

• Env vars implied auto-read but aren't: the shell snippet WORKOS_API_KEY=... ruby app.rb suggested the SDK reads WORKOS_API_KEY/WORKOS_CLIENT_ID automatically — no runtime code does. Reworded to make explicit configuration via WorkOS.configure the documented path.
• PKCE example raised ArgumentError: get_authorization_url_with_pkce requires provider, connection_id, or organization_id; the example passed only redirect_uri. Added provider: "authkit".
• cookie_password validation timing: errors are raised at session load/seal/unseal time, not "at SDK init time". Reworded.
• Idempotency-Key scope: the header is only attached to POST/PUT/PATCH (caller-supplied keys on DELETE are silently ignored; retried DELETEs never get one). Made the claim precise.
• Error example didn't match the prose: transport failures raise WorkOS::APIConnectionError (subclass of WorkOS::Error, not APIError), which the example's rescue never caught. Added the rescue clause and clarified the hierarchy.
• Added the missing "requires Ruby 3.3+" statement (gemspec required_ruby_version), and scoped "every API call accepts request_options:" to HTTP-making methods (URL helpers like get_authorization_url don't take it).