WorkOS Events API Reference

Step 1: Fetch Documentation

STOP. WebFetch the relevant docs for latest implementation details before proceeding.

• https://workos.com/docs/reference/events
• https://workos.com/docs/reference/events/list

What This Skill Covers

This skill teaches agents how to interact with the WorkOS Events API to retrieve audit trail events. The Events API provides read-only access to event data generated by WorkOS services (SSO, Directory Sync, Admin Portal, etc.).

Endpoint Catalog

Note: The Events API is read-only. There are no POST, PUT, or DELETE operations. Events are created automatically by WorkOS when actions occur in your application.

Authentication

All Events API requests require API key authentication:

Authorization: Bearer sk_your_api_key_here

Your API key must:

• Start with sk_ (secret key prefix)
• Have “Events” read permissions enabled in the WorkOS Dashboard
• Be kept secure and never committed to version control

Operation Decision Tree

Need to retrieve events?
├─ Listing all recent events → GET /events (no filters)
├─ Events for specific organization → GET /events?organization_id=org_123
├─ Events of specific type → GET /events?events[]=user.created
├─ Events in time range → GET /events?range_start=2024-01-01&range_end=2024-01-31
├─ Paginating through results → GET /events?after=event_456
└─ Multiple filters combined → Use query parameters together

Events are read-only. You cannot create, update, or delete events via the API.

Request Patterns

List Events (No Filters)

curl https://api.workos.com/events \
  -H "Authorization: Bearer sk_your_api_key"

Filter by Organization

curl "https://api.workos.com/events?organization_id=org_01EHQMYV6MBK39QC5PZXHY59C3" \
  -H "Authorization: Bearer sk_your_api_key"

Filter by Event Types

curl "https://api.workos.com/events?events[]=user.created&events[]=user.updated" \
  -H "Authorization: Bearer sk_your_api_key"

Filter by Date Range

curl "https://api.workos.com/events?range_start=2024-01-01T00:00:00Z&range_end=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer sk_your_api_key"

Pagination (Next Page)

curl "https://api.workos.com/events?after=event_01HZWQQXK4Q1YP8VQRQHFX9TY2" \
  -H "Authorization: Bearer sk_your_api_key"

Response Pattern

Successful responses return a paginated list:

{
  "object": "list",
  "data": [
    {
      "id": "event_01HZWQQXK4Q1YP8VQRQHFX9TY2",
      "event": "user.created",
      "created_at": "2024-01-15T10:30:00.000Z",
      "data": {
        "user": {
          "id": "user_01HZWQPX3K4Q1YP8VQRQHFX9TY",
          "email": "user@example.com",
          "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3"
        }
      }
    }
  ],
  "list_metadata": {
    "after": "event_01HZWQQXK4Q1YP8VQRQHFX9TY2",
    "before": null
  }
}

Pagination Handling

The Events API uses cursor-based pagination:

1. First page: Call GET /events without after or before parameters
2. Next page: Use the list_metadata.after value from the response as the after parameter
3. Previous page: Use the list_metadata.before value from the response as the before parameter
4. End of results: When list_metadata.after is null, you’ve reached the last page

Default page size is 10 events. Maximum is 100 (use limit parameter).

Example pagination loop (pseudocode):

after_cursor = null
do {
  response = GET /events?after={after_cursor}&limit=100
  process(response.data)
  after_cursor = response.list_metadata.after
} while (after_cursor != null)

Error Code Mapping

Rate Limits

• Default limit: 600 requests per minute per API key
• When rate limited (429), the response includes Retry-After header (seconds)
• Recommended retry strategy: exponential backoff starting at Retry-After value

Example retry logic:

retry_delay = 1 second
max_retries = 3

for attempt in 1..max_retries:
  response = GET /events
  if response.status == 429:
    wait(retry_delay)
    retry_delay *= 2
  else:
    break

Query Parameters Reference

After fetching docs, you’ll find these parameters:

Combine parameters with &. All parameters are optional.

SDK Usage Patterns

Node.js

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

const workos = new WorkOS(process.env.WORKOS_API_KEY);

// List all events
const events = await workos.events.listEvents();

// Filter by organization
const orgEvents = await workos.events.listEvents({
  organizationId: 'org_01EHQMYV6MBK39QC5PZXHY59C3'
});

// Filter by event types
const userEvents = await workos.events.listEvents({
  events: ['user.created', 'user.updated']
});

// Pagination
const page1 = await workos.events.listEvents({ limit: 100 });
const page2 = await workos.events.listEvents({ 
  limit: 100, 
  after: page1.listMetadata.after 
});

Python

from workos import WorkOSClient

client = WorkOSClient(api_key=os.environ['WORKOS_API_KEY'])

# List all events
events = client.events.list_events()

# Filter by organization
org_events = client.events.list_events(
    organization_id='org_01EHQMYV6MBK39QC5PZXHY59C3'
)

# Filter by event types
user_events = client.events.list_events(
    events=['user.created', 'user.updated']
)

# Pagination
page1 = client.events.list_events(limit=100)
page2 = client.events.list_events(
    limit=100, 
    after=page1.list_metadata['after']
)

Verification Commands

Test API Key Access

curl https://api.workos.com/events?limit=1 \
  -H "Authorization: Bearer sk_your_api_key"

Expected: 200 OK with event list (even if empty)

Test Organization Filtering

# Replace with a real organization ID from your account
curl "https://api.workos.com/events?organization_id=org_01EHQMYV6MBK39QC5PZXHY59C3&limit=5" \
  -H "Authorization: Bearer sk_your_api_key"

Expected: 200 OK with events only from that organization

Test Date Range Filtering

curl "https://api.workos.com/events?range_start=2024-01-01T00:00:00Z&range_end=2024-12-31T23:59:59Z&limit=5" \
  -H "Authorization: Bearer sk_your_api_key"

Expected: 200 OK with events within date range

Test Invalid Authentication

curl https://api.workos.com/events \
  -H "Authorization: Bearer invalid_key"

Expected: 401 Unauthorized with error code unauthorized

Common Integration Patterns

Pattern 1: Export All Events for Analysis

async function exportAllEvents() {
  const allEvents = [];
  let afterCursor = null;
  
  do {
    const response = await workos.events.listEvents({
      limit: 100,
      after: afterCursor
    });
    
    allEvents.push(...response.data);
    afterCursor = response.listMetadata.after;
  } while (afterCursor);
  
  return allEvents;
}

Pattern 2: Monitor Specific Event Types

async function monitorUserEvents() {
  const events = await workos.events.listEvents({
    events: ['user.created', 'user.updated', 'user.deleted'],
    limit: 100
  });
  
  // Process each event
  for (const event of events.data) {
    console.log(`${event.event} at ${event.created_at}`);
    // Your business logic here
  }
}

Pattern 3: Organization Activity Report

async function getOrganizationActivity(organizationId, startDate, endDate) {
  const events = await workos.events.listEvents({
    organizationId,
    range_start: startDate.toISOString(),
    range_end: endDate.toISOString(),
    limit: 100
  });
  
  return events.data;
}

Event Types Overview

After fetching docs, you’ll find event types like:

• user.created — new user provisioned
• user.updated — user attributes changed
• user.deleted — user deprovisioned
• authentication.succeeded — successful login
• authentication.failed — failed login attempt
• dsync.activated — directory sync connection established
• dsync.deleted — directory sync connection removed

Each event type has a specific data structure. Check the fetched docs for the full event catalog and data schemas.

Related Skills

• workos-events — Feature overview and webhook setup for Events
• workos-audit-logs — Viewing events through the Audit Logs UI
• workos-api-organization — Managing organizations referenced in event filters
• workos-api-directory-sync — Understanding directory sync events
• workos-api-sso — Understanding SSO-related authentication events