From c0e28a4e796e5d58295bbd7f68248b82cd057b37 Mon Sep 17 00:00:00 2001
From: Swaroop Akkineni <swaroop@workos.com>
Date: Tue, 3 Nov 2026 18:22:05 -0500
Subject: [PATCH] feat(audit-logs): make occurredAt optional when creating
 events

---
 src/audit-logs/audit-logs.spec.ts             | 46 +++++++++++++++++++
 src/audit-logs/audit-logs.ts                  |  1 -
 ...reate-audit-log-event-options.interface.ts |  5 +-
 ...eate-audit-log-event-options.serializer.ts |  4 +-
 4 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/src/audit-logs/audit-logs.spec.ts b/src/audit-logs/audit-logs.spec.ts
index 47e30ff33..398c816b4 100644
--- a/src/audit-logs/audit-logs.spec.ts
+++ b/src/audit-logs/audit-logs.spec.ts
@@ -141,6 +141,52 @@ describe('AuditLogs', () => {
   });
 
   describe('createEvent', () => {
+    it('omits occurred_at when occurredAt is not provided', async () => {
+      fetchOnce({ success: true });
+
+      const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+      const eventWithoutTimestamp: CreateAuditLogEventOptions = {
+        action: event.action,
+        actor: event.actor,
+        targets: event.targets,
+        context: event.context,
+      };
+
+      await workos.auditLogs.createEvent('org_123', eventWithoutTimestamp);
+
+      expect(fetchBody()).toMatchObject({
+        organization_id: 'org_123',
+        event: { action: event.action },
+      });
+      expect(fetchBody().event).not.toHaveProperty('occurred_at');
+    });
+
+    it('omits occurred_at when occurredAt is undefined', async () => {
+      fetchOnce({ success: true });
+
+      const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+
+      await workos.auditLogs.createEvent('org_123', {
+        ...event,
+        occurredAt: undefined,
+      });
+
+      expect(fetchBody().event).not.toHaveProperty('occurred_at');
+    });
+
+    it('preserves an explicitly provided occurredAt', async () => {
+      fetchOnce({ success: true });
+
+      const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+
+      await workos.auditLogs.createEvent('org_123', {
+        ...event,
+        occurredAt: new Date('2026-11-03T12:34:56.789Z'),
+      });
+
+      expect(fetchBody().event.occurred_at).toBe('2026-11-03T12:34:56.789Z');
+    });
+
     describe('with an idempotency key', () => {
       it('includes an idempotency key with request', async () => {
         const workosSpy = jest.spyOn(WorkOS.prototype, 'post');
diff --git a/src/audit-logs/audit-logs.ts b/src/audit-logs/audit-logs.ts
index de34dc8a9..9c4fef459 100644
--- a/src/audit-logs/audit-logs.ts
+++ b/src/audit-logs/audit-logs.ts
@@ -97,7 +97,6 @@ export class AuditLogs {
    *
    * To achieve idempotency, you can add `Idempotency-Key` request header to a Create Event request with a unique string as the value. Each subsequent request matching this unique string will return the same response. We suggest using [v4 UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) for idempotency keys to avoid collisions.
    *
-   * Idempotency keys expire after 24 hours. The API will generate a new response if you submit a request with an expired key.
    * @param payload - Object containing organizationId, event.
    * @returns {Promise<void>}
    * @throws {BadRequestException} 400
diff --git a/src/audit-logs/interfaces/create-audit-log-event-options.interface.ts b/src/audit-logs/interfaces/create-audit-log-event-options.interface.ts
index b74649d8f..06f4f4aee 100644
--- a/src/audit-logs/interfaces/create-audit-log-event-options.interface.ts
+++ b/src/audit-logs/interfaces/create-audit-log-event-options.interface.ts
@@ -17,7 +17,8 @@ export interface AuditLogTarget {
 export interface CreateAuditLogEventOptions {
   action: string;
   version?: number;
-  occurredAt: Date;
+  /** Defaults to the time WorkOS accepts the event when omitted. */
+  occurredAt?: Date;
   actor: AuditLogActor;
   targets: AuditLogTarget[];
   context: {
@@ -30,7 +31,7 @@ export interface CreateAuditLogEventOptions {
 export interface SerializedCreateAuditLogEventOptions {
   action: string;
   version?: number;
-  occurred_at: string;
+  occurred_at?: string;
   actor: AuditLogActor;
   targets: AuditLogTarget[];
   context: {
diff --git a/src/audit-logs/serializers/create-audit-log-event-options.serializer.ts b/src/audit-logs/serializers/create-audit-log-event-options.serializer.ts
index fc316ac22..c585283fe 100644
--- a/src/audit-logs/serializers/create-audit-log-event-options.serializer.ts
+++ b/src/audit-logs/serializers/create-audit-log-event-options.serializer.ts
@@ -8,7 +8,9 @@ export const serializeCreateAuditLogEventOptions = (
 ): SerializedCreateAuditLogEventOptions => ({
   action: event.action,
   version: event.version,
-  occurred_at: event.occurredAt.toISOString(),
+  ...(event.occurredAt === undefined
+    ? {}
+    : { occurred_at: event.occurredAt.toISOString() }),
   actor: event.actor,
   targets: event.targets,
   context: {