WorkOS Events

WorkOS Events give you a single, chronological feed of everything happening across your WorkOS environment: authentication attempts, directory sync activity, SSO connection changes, organization and membership updates, role and permission changes, and more. RunReveal polls the WorkOS Events API and ingests every event type, giving security and compliance teams a durable audit trail and a foundation for detections on identity activity.

Setup

WorkOS Events are collected via API polling against the WorkOS Events API (GET /events).

1. Go to Sources in RunReveal
2. Click the WorkOS Events source tile
3. Give it a name
4. Fill in your API Key
5. Optionally set an Organization ID Filter to scope ingestion to a single WorkOS organization. Leave it blank to ingest events across all organizations.
6. Click Connect Source

API Key Configuration

Creating the API Key:

1. Sign in to the WorkOS Dashboard
2. Navigate to API Keys
3. Create an API key (or reuse an existing one) with access to the Events API
4. Copy the key — store it securely

The key is sent to WorkOS as a bearer credential in the Authorization header on every request.

Collected Events

RunReveal stores the WorkOS event name (e.g. authentication.sso_succeeded, dsync.user.created, organization.updated) in the eventName field and normalizes the most useful fields across the different WorkOS event shapes. Event categories include:

• authentication — email verification, magic auth, MFA, OAuth, password, passkey, and SSO successes and failures
• dsync — directory sync activation, user and group lifecycle changes
• connection — SSO connection activation, deactivation, and certificate events
• organization / organization_membership / organization_domain — organization lifecycle and membership changes
• session — session creation and revocation
• user — user create, update, and delete
• role / permission / api_key / vault — and more

Event Data Structure

RunReveal normalizes the following from each event where present:

• Event Name — The WorkOS event type (event), stored as eventName
• Actor Information — Email, user id, and username (actor.email, actor.id, actor.username)
• Organization — The organization id (woOrganizationID / tags.organization_id), including auth events that nest it under data.sso.organization_id
• Network Context — The client IP address (srcIP) and user agent (tags.user_agent)

Data Collection

• Collection Method: API polling every minute
• Pagination: Cursor-based, walking forward in time with a high water mark on the last event id
• Backfill: On first connection RunReveal backfills the last 30 days of events (bounded per poll so a large backlog drains over multiple polls)
• Event Format: JSON with normalized fields for consistent querying

Verify It's Working

Once added the source logs should begin flowing within a few minutes.

You can validate we are receiving your logs by running the following SQL query.

SELECT * FROM runreveal.logs WHERE sourceType = 'workos-events' LIMIT 1

Schema

The following columns are exposed for this source. RunReveal applies schema normalization across all sources, ensuring uniform field names and data types for cross-source queries and reusable detection logic.

Helpful Links

• WorkOS Events API - Reference for the Events API and pagination
• WorkOS Event Types - The full catalog of event types WorkOS emits
• WorkOS Dashboard - Manage API keys and configuration