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.

Create an Audit Log Event.

This API supports idempotency which guarantees that performing the same operation multiple times will have the same result as if the operation were performed only once. This is handy in situations where you may need to retry a request due to a failure or prevent accidental duplicate requests from creating more than one resource.

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

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(),
    version: 1,
    actor: {
      type: 'user',
      id: 'user_TF4C5938',
      name: 'Jon Smith',
      metadata: {
        role: 'admin',
      },
    },
    targets: [
      {
        type: 'user',
        id: 'user_98432YHF',
        name: 'Jon Smith',
      },
      {
        type: 'team',
        id: 'team_J8YASKA2',
        metadata: {
          owner: 'user_01GBTCQ2',
        },
      },
    ],
    context: {
      location: '1.1.1.1',
      userAgent: 'Chrome/104.0.0.0',
    },
    metadata: {
      extra: 'data',
    },
  },
  {
    idempotencyKey: '884793cd-bef4-46cf-8790-ed49257a09c6',
  },
);

An object representing an Audit Log Schema.

const auditLogSchema = {
  object: 'audit_log_schema',
  version: 1,
  targets: [{ type: 'user', metadata: {} }],
  actor: { metadata: {} },
  metadata: {},
  createdAt: '2024-10-14T15:09:44.537Z',
};

Creates a new Audit Log schema used to validate the payload of incoming Audit Log Events. If the action does not exist, it will also be created.

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

const workos = new WorkOS('sk_example_123456789');

const schema = await workos.auditLogs.createSchema({
  action: 'user.viewed_invoice',
  actor: {
    metadata: {
      role: 'string',
    },
  },
  targets: [
    {
      type: 'user',
      metadata: {
        status: 'string',
      },
    },
  ],
  metadata: {
    invoice_id: 'string',
  },
});

Get a list of all schemas for the Audit Logs action identified by :name.

curl https://api.workos.com/audit_logs/actions/user.viewed_invoice/schemas \
  --header "Authorization: Bearer sk_example_123456789"

Get a list of all Audit Log actions in the current environment.

curl https://api.workos.com/audit_logs/actions \
  --header "Authorization: Bearer sk_example_123456789"

An object representing an Audit Log Export.

const auditLogExport = {
  object: 'audit_log_export',
  id: 'audit_log_export_01GBZK5MP7TD1YCFQHFR22180V',
  state: 'ready',
  url: 'https://exports.audit-logs.com/audit-log-exports/export.csv',
  created_at: '2022-09-02T17:14:57.094Z',
  updated_at: '2022-09-02T17:14:57.094Z',
};

Create an Audit Log Export.

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

const workos = new WorkOS('sk_example_123456789');

const auditLogExport = await workos.auditLogs.createExport({
  organizationId: 'org_01EHWNCE74X7JSDV0X3SZ3KJNY',
  rangeStart: new Date('2022-07-02T18:09:06.996Z'),
  rangeEnd: new Date('2022-09-02T18:09:06.996Z'),
  actions: ['user.signed_in'],
  actors: ['Jon Smith'],
  targets: ['team'],
});

Get an Audit Log Export.

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

const workos = new WorkOS('sk_example_123456789');

const auditLogExport = await workos.auditLogs.getExport(
  'audit_log_export_01GBZK5MP7TD1YCFQHFR22180V',
);

Get the configured event retention period for the given Organization.

curl https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/audit_logs_retention \
  --header "Authorization: Bearer sk_example_123456789"

Set the event retention period for the given Organization.

curl --request PUT \
  --url https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/audit_logs_retention \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d '{ "retention_period_in_days": 30 }'

The Audit Log Configuration endpoint provides a single view of an organization’s audit logging setup. It includes retention settings (how long audit logs are stored), the audit log state (active, inactive, or disabled), and – if configured – the audit log stream, which sends events to external destinations like Splunk, Datadog, S3, Google Cloud Storage, or a custom HTTPS endpoint.

The log_stream field is optional and only appears if the organization has a stream configured. If no stream is set up, the response includes only the audit log retention and state information.

curl https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/audit_log_configuration \
  --header "Authorization: Bearer sk_example_123456789"