Skip to main content
Audit logging requires the Audit Logging add-on. See Add-ons pricing for details.

​
Base Event Schema

All audit log events share a common structure with four main components:

​
Actor

The user who performed the action.
​
actor.type
string
required
Always set to "user"
​
actor.id
string
required
User’s unique identifier
​
actor.name
string
required
User’s full name (first name + last name)
​
actor.metadata
object
required

​
Targets

The resources affected by the action. Each event can have multiple targets.
​
targets
array
required
Array of target objects

​
Context

Information about when and where the action occurred.
​
context.location
string
required
IP address of the request, or "unknown" if unavailable. Maximum 45 characters (IPv6 compatible).
​
context.userAgent
string
required
User agent string from the request, or "unknown" if unavailable. Maximum 500 characters.

​
Metadata

Additional information specific to the action.
​
metadata.source
string
required
User-facing page route where the action was initiated
Additional metadata fields vary by event type and are documented in each event’s specific schema.

​
Field Conventions

​
Naming

  • Action names use snake_case with dots: api_key.create, organization.update_name
  • Metadata fields use snake_case: first_name, organization_id, status_from
  • Format follows <resource>.<action> pattern

​
Value Constraints

  • String fields are truncated to prevent exceeding WorkOS limits
  • Default truncation: 500 characters
  • IP addresses: maximum 45 characters
  • User agents: maximum 500 characters
  • All values are sanitized before storage

​
Optional Fields

  • impersonator_email and impersonator_reason are present but empty when not applicable
  • context.location and context.userAgent default to "unknown" when unavailable
  • Some metadata fields are optional and only present for specific events

​
Event Categories

API Keys

Key creation, updates, revocations, and access

MCP Proxies

Proxy configuration, OAuth flows, and connections

Projects

Project creation, settings, and membership views

Project Memberships

User access grants and revocations

Organizations

Organization settings, domains, and membership views

External Apps

OAuth consent and login approval flows

SSO

Single sign-on configuration and connections

Directory Sync

User provisioning and directory connections

Audit Log Streams

Audit log portal access and SIEM configurations

Users

User profile and settings access

Analytics

Usage analytics and metrics access

​
Common Patterns

​
View Events

Events with .view_* or .list_* suffixes record when users access information without making changes. These events:
  • Include the viewed resource as a target
  • Record the page route in metadata.source
  • Do not include change tracking metadata

​
Update Events

Events with .update or .update_* suffixes record modifications to resources. These events:
  • Include changes metadata with before/after values for modified fields
  • Use format: {field_name: {from: old_value, to: new_value}}
  • Status changes use dedicated status_from and status_to metadata fields

​
Create and Delete Events

Events with .create and .delete suffixes record resource lifecycle events. These events:
  • Create events include full initial configuration in target metadata
  • Delete events typically have minimal metadata (resource was removed)
  • Both include the affected resource and its parent (e.g., API key and project)

​
Multi-Target Events

Many events include multiple targets to provide full context:
  • Primary resource (e.g., api_key)
  • Parent resource (e.g., project)
  • Related resources (e.g., organization)
This structure allows filtering events by any affected resource in the audit logs portal.