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

Method Path Purpose

GET /events

List events with filtering and pagination

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:

• First page: Call GET /events without after or before parameters

• Next page: Use the list_metadata.after value from the response as the after parameter

• Previous page: Use the list_metadata.before value from the response as the before parameter

• 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

Status Error Code Cause Fix

401 unauthorized Missing or invalid API key Check Authorization header includes Bearer sk_...

401 unauthorized API key lacks Events read permission Enable Events permission in WorkOS Dashboard

400 invalid_request Invalid query parameter format Check parameter names match docs (e.g., events[] not event_types )

400 invalid_request Invalid date format in range_start/range_end Use ISO 8601 format: 2024-01-01T00:00:00Z

404 not_found Invalid organization_id Verify organization exists using Organizations API

429 rate_limit_exceeded Too many requests Implement exponential backoff (start with 1s delay, double on retry)

500 internal_error WorkOS service issue Retry with exponential backoff, contact support if persists

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:

Parameter Type Description Example

events[]

array Filter by event types (repeatable) events[]=user.created&events[]=user.updated

organization_id

string Filter by organization organization_id=org_123

range_start

ISO 8601 Start of date range (inclusive) range_start=2024-01-01T00:00:00Z

range_end

ISO 8601 End of date range (inclusive) range_end=2024-01-31T23:59:59Z

limit

integer Events per page (1-100, default 10) limit=50

after

string Cursor for next page after=event_456

before

string Cursor for previous page before=event_123

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