Audit Logs

Ingest and export Audit Log Events from your application.

Audit Logs are a collection of events that contain information relevant to notable actions taken by users in your application. Every event in the collection contains details regarding what kind of action was taken (action), who performed the action (actor), what resources were affected by the action (targets), and additional details of when and where the action took place. For example:

 {
  "action": "user.signed_in",
  "occurred_at": "2022-08-29T19:47:52.336Z",
  "actor": {
    "type": "user",
    "id": "user_01GBNJC3MX9ZZJW1FSTF4C5938"
  },
  "targets": [
    {
      "type": "team",
      "id": "team_01GBNJD4MKHVKJGEWK42JNMBGS"
    }
  ],
  "context": {
    "location": "123.123.123.123",
    "user_agent": "Chrome/104.0.0.0"
  }
}

These events are similar to application logs and analytic events, but are fundamentally different in their intent. They aren’t typically used for active monitoring/alerting; rather, they exist as a paper trail of potentially sensitive actions taken by members of an organization for compliance and security reasons.

What you’ll build

Follow this guide to:

Configure and emit Audit Log Events
Export Audit Log Events
Create custom metadata schemas for Audit Log Events
Create new versions of Audit Log Event schemas

Before getting started

Make sure you have:

A WorkOS account

Emit an Audit Log Event

Install the WorkOS SDK

Install the WorkOS SDK for your language. Choose a language below to see the appropriate instructions.

Set secrets

Store your API key and client ID as managed secrets, such as WORKOS_API_KEY and WORKOS_CLIENT_ID. Pass them to the SDKs either as environment variables or directly in your app’s configuration.

Environment variables

 WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

Configure Audit Log Event schemas in the Dashboard

Configure the allowed event schemas before emitting any Audit Log Events. Sign in to your WorkOS Dashboard, click “Create an event”, enter user.signed_in for action and team for targets, then click “Save event”.

A screenshot showing how to create an audit log event in the WorkOS dashboard.

Get an Organization ID

Retrieve the ID of an Organization from the Dashboard. All events are scoped to an Organization, so you need this ID to emit events.

A screenshot showing where to find an Organization ID in the WorkOS dashboard.

Emit Events

Use the Organization ID to emit an Audit Log Event with the action and targets you configured earlier.

Emit event

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.auditLogs.createEvent('org_01EHWNCE74X7JSDV0X3SZ3KJNY', {
  action: 'user.signed_in',
  occurredAt: new Date(),
  actor: {
    type: 'user',
    id: 'user_01GBNJC3MX9ZZJW1FSTF4C5938',
  },
  targets: [
    {
      type: 'team',
      id: 'team_01GBNJD4MKHVKJGEWK42JNMBGS',
    },
  ],
  context: {
    location: '123.123.123.123',
    userAgent: 'Chrome/104.0.0.0',
  },
});

Idempotency

Provide an idempotency-key header with your event creation request to prevent duplicate events when retrying requests. If you omit this header, WorkOS automatically generates a key based on the event content.

When you provide an idempotency key:

WorkOS creates a hashed key combining your provided key with the event data
Subsequent requests with the same idempotency key and event data return the same response
This prevents duplicate events from network retries or other issues

When you omit the idempotency key:

WorkOS automatically generates one using the event content
This provides basic duplicate protection based on event data alone

View ingested events in the Dashboard

Open the Dashboard and navigate to the Organization to view the emitted events.

A screenshot showing Audit Log events for an organization in the WorkOS dashboard.