Audit Logs

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.

{
  "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.

This guide will show you how to:

1. Configure and emit Audit Log Events
2. Export Audit Log Events
3. Create custom metadata schemas for Audit Log Events
4. Create new versions of Audit Log Event schemas

To get the most out of this guide, you’ll need:

• A WorkOS account

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

As a best practice, your WorkOS API key should be kept secret and set as an environment variable on process start. The SDK is able to read the key automatically if you store it in an environment variable named WORKOS_API_KEY; otherwise, you will need to set it manually. The Client ID should also be set dynamically based on the release environment.

WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

Before you can emit any Audit Log Events you must configure the allowed event schemas. Start by clicking Create an event and enter user.signed_in for action, user for targets, and click save.

All events are scoped to an Organization, so you will need the ID of an Organziation in order to emit events.

Using the ID from the Organization, emit an Audit Log Event with the action and targets previously configured.

import WorkOS from '@workos-inc/node';
const workos = new WorkOS('sk_example_123456789');
await workos.auditLogs.createEvent('org_01EHWNCE74X7JSDV0X3SZ3KJNY', {
  action: 'user.signed_in',
  occurred_at: new Date(),
  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',
  },
});

Once you have successfully emitted events with the WorkOS SDK, you can view them in the Dashboard under the Organization that the events are associated with.