WorkOS Docs Homepage
Audit Logs

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.

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:

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.
Describes an Enterprise 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.

Don't see an SDK you need? Contact us to request an SDK!

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.

Environment Variables

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”.

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

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

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

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

Emit event

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.

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