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:

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

Audit Log Event

An individual event that represents an action taken by an actor within your app.

Audit Log Export

A collection of Audit Log Events that are exported from WorkOS as a CSV file.

Organization

Describes a customer where Audit Log Events originate from.

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. To start, click “Create an event” and enter user.signed_in for action, team for targets, and click “Save event”.

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.