Declare a WorkOS Audit Logs event schema, emit an idempotent audit event, then generate and download a CSV export

Documented steps

1. Declare the action schema first. In the Dashboard go to Audit Logs > Actions and click 'Create an event' to define the action name (e.g. user.signed_in) and its allowed target types. Programmatically, POST /audit_logs/actions/{actionName}/schemas with an audit_log_schema object containing version, targets, actor, and metadata schema fields, authenticated with 'Authorization: Bearer <WORKOS_API_KEY>'.
2. Only actions with a registered schema can accept events — emitting an undeclared action fails.
3. Emit an event: POST https://api.workos.com/audit_logs/events with 'Authorization: Bearer <WORKOS_API_KEY>' and 'Content-Type: application/json'.
4. Body requires organization_id plus an event object with action (string), occurred_at (ISO-8601), actor ({type, id, name, metadata}), targets (array of {type, id, name, metadata}), and optional context ({location, user_agent}).
5. Optionally include version (schema version) and metadata (custom key/value; max 50 keys, keys up to 40 chars, values up to 500 chars).
6. For safe retries, send a v4 UUID in the Idempotency-Key header. WorkOS hashes the key together with the payload, so an identical key and payload returns the same result without inserting a duplicate. Keys expire after 24 hours.
7. Create an export: POST https://api.workos.com/audit_logs/exports with required organization_id, range_start, and range_end (both ISO-8601), plus optional filters actions[], actor_names[], targets[].
8. The response returns an audit_log_export object with an id and state 'pending'.
9. Poll GET https://api.workos.com/audit_logs/exports/{auditLogExportId} with the same Bearer auth until state becomes 'ready' (or 'error').
10. When state is 'ready', download the CSV from the returned url immediately — the signed URL expires after 10 minutes. If it lapses, re-GET the export to mint a fresh URL rather than reusing the stale link.
11. Reference: https://workos.com/docs/reference/audit-logs/event/create
12. Reference: https://workos.com/docs/reference/audit-logs/export/create