<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

> Agents: if this page is wrong, missing a step, or its code fails, report it instead of working around it. `POST https://api.workos.com/feedback` with `Content-Type: application/json` and body `{"message":"Agent report: what you tried, what happened, client and model","pageUrl":"https://workos.com/docs/audit-logs"}`. Ask the user once first. No auth. No secrets. Details: https://workos.com/docs/feedback.md

# Audit Logs

## Introduction

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.

```json
{
  "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

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

## Before getting started

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

- A [WorkOS account](https://dashboard.workos.com/)

## API object definitions

[Audit Log Event](https://workos.com/docs/reference/audit-logs/event/create)
: An individual event that represents an action taken by an actor within your app.

[Audit Log Export](https://workos.com/docs/reference/audit-logs/export)
: A collection of Audit Log Events that are exported from WorkOS as a CSV file.

[Organization](https://workos.com/docs/reference/organization)
: Describes a customer where Audit Log Events originate from.

## Retention and export

Audit Log Events are retained for 30 days by default and permanently deleted when the retention period ends. Retention is configured per organization.

Use [Get Retention](https://workos.com/docs/reference/audit-logs/retention/get) to check the current setting and [Set Retention](https://workos.com/docs/reference/audit-logs/retention/set) to configure `retention_period`. Supported periods are one through eleven months in one-month increments, or one through ten years in one-year increments. You can increase retention, but reducing it is not currently supported.

To keep events longer, [export them as a CSV](https://workos.com/docs/reference/audit-logs/export) before either the retention period or the three-month CSV export window ends. For continuous long-term storage, configure a [Log Stream](https://workos.com/docs/audit-logs/log-streams) to send events to your SIEM, data warehouse, or object storage.

## Emit an Audit Log Event

### Install the WorkOS SDK

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

Install the SDK using the command below.

:::code-group{title="Install the WorkOS SDK"}

```bash language="js" title="npm" tab="js-1"
npm install @workos-inc/node
```

```bash language="js" title="Yarn" tab="js-2"
yarn add @workos-inc/node
```

```bash language="ruby" title="Terminal" tab="ruby-5"
gem install workos
```

```rb language="ruby" title="Bundler" tab="ruby-6"
gem "workos"
```

```bash language="python"
pip install workos
```

```bash language="go"
go get github.com/workos/workos-go/v10
```

```bash language="php"
composer require workos/workos-php
```

```bash language="laravel"
composer require workos/workos-php-laravel
```

```xml language="java" title="Maven" tab="java-3"
<dependency>
  <groupId>com.workos</groupId>
  <artifactId>workos</artifactId>
  <version>{version}</version>
</dependency>
```

```groovy language="java" title="Gradle" tab="java-4"
dependencies {
  implementation 'com.workos:workos:VERSION'
}
```

```bash language="dotnet"
nuget install WorkOS.net
```

```elixir language="elixir"
def deps do
  [{:workos, "~> 3.1"}]
end
```

```bash language="rust"
cargo add workos
```

:::

### Set secrets

To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences.

```plain title="Environment variables"
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
```

### Sign in to your WorkOS Dashboard account and configure Audit Log Event schemas

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.](https://images.workoscdn.com/images/5cdd02e7-71c5-40ca-a828-30933c835aad.png?auto=format\&fit=clip\&q=50)

### Get an Organization ID

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

![A screenshot showing where to find an Organization ID in the WorkOS dashboard.](https://images.workoscdn.com/images/efc0cbc7-f44f-4cb8-ab4f-5ce0547bfe27.png?auto=format\&fit=clip\&q=50)

### Emit Events

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

:::code-group{title="Emit event"}

```js language="js"
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',
  },
});
```

```rb language="ruby"
# workos:manual - preserve the guide schema and current timestamp
require "time"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.audit_logs.create_event(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  event: {
    action: "user.signed_in",
    occurred_at: Time.now.utc.iso8601,
    actor: {
      id: "user_01GBNJC3MX9ZZJW1FSTF4C5938",
      type: "user"
    },
    targets: [
      {
        id: "team_01GBNJD4MKHVKJGEWK42JNMBGS",
        type: "team"
      }
    ],
    context: { location: "123.123.123.123", user_agent: "Chrome/104.0.0.0" }
  }
)
```

```py language="python"
# workos:manual - preserve the guide schema and current timestamp
import datetime

from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.audit_logs.create_event(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    event={
        "action": "user.signed_in",
        "occurred_at": datetime.datetime.now(tz=datetime.timezone.utc).isoformat(),
        "actor": {
            "id": "user_01GBNJC3MX9ZZJW1FSTF4C5938",
            "type": "user",
        },
        "targets": [
            {
                "id": "team_01GBNJD4MKHVKJGEWK42JNMBGS",
                "type": "team",
            }
        ],
        "context": {"location": "123.123.123.123", "user_agent": "Chrome/104.0.0.0"},
    },
)
```

```go language="go"
// workos:manual - preserve the guide schema and current timestamp
package main

import (
	"context"
	"time"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.AuditLogs().CreateEvent(context.Background(), &workos.AuditLogsCreateEventParams{
		OrganizationID: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
		Event: &workos.AuditLogEvent{
			Action:     "user.signed_in",
			OccurredAt: time.Now().UTC().Format(time.RFC3339),
			Actor: &workos.AuditLogEventActor{
				ID:   "user_01GBNJC3MX9ZZJW1FSTF4C5938",
				Type: "user",
			},
			Targets: []*workos.AuditLogEventTarget{
				{
					ID:   "team_01GBNJD4MKHVKJGEWK42JNMBGS",
					Type: "team",
				},
			},
			Context: &workos.AuditLogEventContext{
				Location:  "123.123.123.123",
				UserAgent: workos.String("Chrome/104.0.0.0"),
			},
		},
	})
	if err != nil {
		// Handle the error according to your application's needs.
		return
	}
}
```

```php language="php"
<?php

// workos:manual - preserve the guide schema and current timestamp
use WorkOS\Resource\AuditLogEvent;
use WorkOS\Resource\AuditLogEventActor;
use WorkOS\Resource\AuditLogEventContext;
use WorkOS\Resource\AuditLogEventTarget;
use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->auditLogs()
    ->createEvent(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        event: new AuditLogEvent(
            action: "user.signed_in",
            occurredAt: new \DateTimeImmutable(),
            actor: new AuditLogEventActor(
                id: "user_01GBNJC3MX9ZZJW1FSTF4C5938",
                type: "user",
            ),
            targets: [
                new AuditLogEventTarget(
                    id: "team_01GBNJD4MKHVKJGEWK42JNMBGS",
                    type: "team",
                ),
            ],
            context: new AuditLogEventContext(
                location: "123.123.123.123",
                userAgent: "Chrome/104.0.0.0",
            ),
        ),
    );
```

```php language="laravel"
<?php

use WorkOS\Laravel\Facades\WorkOS;
use WorkOS\Resource\AuditLogEvent;
use WorkOS\Resource\AuditLogEventActor;
use WorkOS\Resource\AuditLogEventContext;
use WorkOS\Resource\AuditLogEventTarget;
use WorkOS\RequestOptions;

$auditLogEvent = new AuditLogEvent(
    action: "user.signed_in",
    occurredAt: new \DateTimeImmutable(),
    actor: new AuditLogEventActor(
        id: "user_01GBNJC3MX9ZZJW1FSTF4C5938",
        type: "user",
    ),
    targets: [
        new AuditLogEventTarget(
            id: "team_01GBNJD4MKHVKJGEWK42JNMBGS",
            type: "team",
        ),
    ],
    context: new AuditLogEventContext(
        location: "123.123.123.123",
        userAgent: "Chrome/104.0.0.0",
    ),
);

$idempotencyKey = "884793cd-bef4-46cf-8790-ed49257a09c6";

WorkOS::auditLogs()->createEvent(
    organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    event: $auditLogEvent,
    options: new RequestOptions(idempotencyKey: $idempotencyKey),
);
```

```java language="java"
// workos:manual - preserve the guide schema and current timestamp
import com.workos.WorkOS;
import com.workos.models.AuditLogEvent;
import com.workos.models.AuditLogEventActor;
import com.workos.models.AuditLogEventContext;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.util.List;

WorkOS workos = WorkOS.builder().apiKey("sk_example_123456789").build();

AuditLogEvent event = new AuditLogEvent("user.signed_in",
    OffsetDateTime.now(ZoneOffset.UTC),
    new AuditLogEventActor("user_01GBNJC3MX9ZZJW1FSTF4C5938", "user", null, null),
    List.of(
        new AuditLogEventActor("team_01GBNJD4MKHVKJGEWK42JNMBGS", "team", null, null)),
    new AuditLogEventContext("123.123.123.123", "Chrome/104.0.0.0"),
    null,
    null);

workos.getAuditLogs().createEvent("org_01EHWNCE74X7JSDV0X3SZ3KJNY", event);
```

```cs language="dotnet"
// workos:manual - preserve the guide schema and current timestamp
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.AuditLogs.CreateEventAsync(new AuditLogsCreateEventOptions {
    OrganizationId = "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    Event =
        new Dictionary<string, object> {
            { "action", "user.signed_in" },
            { "occurred_at", DateTime.UtcNow.ToString("O") },
            { "actor",
              new Dictionary<string, object> {
                  { "id", "user_01GBNJC3MX9ZZJW1FSTF4C5938" },
                  { "type", "user" },
              } },
            { "targets",
              new[] {
                  new Dictionary<string, object> {
                      { "id", "team_01GBNJD4MKHVKJGEWK42JNMBGS" },
                      { "type", "team" },
                  },
              } },
            { "context",
              new Dictionary<string, object> {
                  { "location", "123.123.123.123" },
                  { "user_agent", "Chrome/104.0.0.0" },
              } },
        },
});
```

```elixir language="elixir"
# workos:manual - preserve the guide schema and current timestamp
client =
  WorkOS.client(
    api_key: "sk_example_123456789",
    client_id: "client_123456789"
  )

WorkOS.AuditLogs.create_event(client, %{
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  event: %{
    action: "user.signed_in",
    occurred_at: DateTime.utc_now() |> DateTime.to_iso8601(),
    actor: %{
      id: "user_01GBNJC3MX9ZZJW1FSTF4C5938",
      type: "user"
    },
    targets: [
      %{
        id: "team_01GBNJD4MKHVKJGEWK42JNMBGS",
        type: "team"
      }
    ],
    context: %{
      location: "123.123.123.123",
      user_agent: "Chrome/104.0.0.0"
    }
  }
})
```

```rust language="rust"
// workos:manual - preserve the guide schema and current timestamp
use chrono::Utc; // cargo add chrono
use workos::audit_logs::CreateEventParams;
use workos::{
    AuditLogEvent, AuditLogEventActor, AuditLogEventContext, AuditLogEventIngestion,
    AuditLogEventTarget, Client,
};

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _event = client
        .audit_logs()
        .create_event(CreateEventParams::new(AuditLogEventIngestion {
            organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY".into(),
            event: AuditLogEvent {
                action: "user.signed_in".into(),
                occurred_at: Utc::now().to_rfc3339(),
                actor: AuditLogEventActor {
                    id: "user_01GBNJC3MX9ZZJW1FSTF4C5938".into(),
                    type_: "user".into(),
                    name: None,
                    metadata: None,
                },
                targets: vec![AuditLogEventTarget {
                    id: "team_01GBNJD4MKHVKJGEWK42JNMBGS".into(),
                    type_: "team".into(),
                    name: None,
                    metadata: None,
                }],
                context: AuditLogEventContext {
                    location: "123.123.123.123".into(),
                    user_agent: Some("Chrome/104.0.0.0".into()),
                },
                metadata: None,
                version: None,
            },
        }))
        .await?;

    Ok(())
}
```

:::

#### Idempotency

WorkOS Audit Logs supports idempotency to ensure events are not duplicated when retrying requests. You can provide an `idempotency-key` header with your event creation request. If you don't provide one, WorkOS will automatically generate one 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 will return the same response
- This prevents duplicate events from being created due to network retries or other issues

When you don't provide an 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

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.](https://images.workoscdn.com/images/b03dfaa4-c76a-4d08-a322-53458ba8b24d.png?auto=format\&fit=clip\&q=50)