Organization Events

Organization events track administrative actions related to organization configuration, domain management, and member access views. These events record changes to organization settings and views of organization-level information.

All organization events include the standard actor, targets, context, and metadata fields. The schemas below show event-specific fields.

organization.create

Records when a new organization is created during user onboarding.

Triggered When

User completes the onboarding flow and creates their first organization.

Event Schema

string

required

organization.create

array

required

Show organization target

string

required

organization

string

required

Organization’s unique identifier

string

required

Organization name

object

required

Empty object (no additional metadata)

string

required

Page route where organization was created (typically onboarding flow route)

Example Event

{
  "action": "organization.create",
  "occurredAt": "2025-01-15T10:30:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {}
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/onboarding"
  }
}

organization.update_name

Records when an organization’s name is changed.

Triggered When

Admin updates the organization name in organization settings.

Event Schema

string

required

organization.update_name

array

required

Show organization target

string

required

organization

string

required

Organization’s unique identifier

string

required

Organization’s new name (post-update)

string

required

Organization’s previous name

string

required

Organization’s new name

string

required

Always organization_settings

Example Event

{
  "action": "organization.update_name",
  "occurredAt": "2025-01-15T14:20:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corporation",
      "metadata": {
        "old_name": "Acme Corp",
        "new_name": "Acme Corporation"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "organization_settings"
  }
}

organization.view_settings

Records when a user views the organization settings page.

Triggered When

User navigates to the organization details/settings page.

Event Schema

string

required

organization.view_settings

array

required

Show organization target

string

required

organization

string

required

Organization’s unique identifier

string

required

Organization name

string

required

Organization name (duplicated for consistency)

string

required

Page route (e.g., /organizations/[orgId]/details)

Example Event

{
  "action": "organization.view_settings",
  "occurredAt": "2025-01-15T09:15:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {
        "name": "Acme Corp"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/details"
  }
}

organization.view_domains

Records when a user views the organization’s domain management page.

Triggered When

User navigates to the organization domains page.

Event Schema

string

required

organization.view_domains

array

required

Show organization target

string

required

organization

string

required

Organization’s unique identifier

string

required

Organization name

string

required

Organization name (duplicated for consistency)

string

required

Page route (e.g., /organizations/[orgId]/domains)

Example Event

{
  "action": "organization.view_domains",
  "occurredAt": "2025-01-15T11:45:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {
        "name": "Acme Corp"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/domains"
  }
}

organization.delete_domain

Records when a domain is removed from an organization.

Triggered When

Admin deletes a verified domain from the organization’s domain list.

Event Schema

string

required

organization.delete_domain

array

required

Show organization_domain target

string

required

organization_domain

string

required

Domain’s unique identifier

string

required

Domain name (e.g., example.com)

string

required

Domain’s unique identifier (same as id)

string

required

Domain name

string

required

Organization’s unique identifier

string

required

Page route where domain was deleted

Example Event

{
  "action": "organization.delete_domain",
  "occurredAt": "2025-01-15T16:00:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization_domain",
      "id": "domain_01JGXYZ789",
      "name": "old-domain.com",
      "metadata": {
        "domain_id": "domain_01JGXYZ789",
        "domain_name": "old-domain.com",
        "organization_id": "org_01JGXYZ456"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/domains"
  }
}

organization.list_memberships

Records when a user views the list of organization members.

Triggered When

User queries the organization members list via the members API endpoint.

Event Schema

string

required

organization.list_memberships

array

required

Show organization target

string

required

organization

string

required

Organization’s unique identifier

string

required

Organization name

string

required

Organization name (duplicated for consistency)

string

required

Page route where members were listed

string

required

Page number in pagination (as string)

string

required

Number of results per page (as string)

string

required

Total number of members returned (as string)

string

Search query used to filter members (empty string if no filter)

Example Event

{
  "action": "organization.list_memberships",
  "occurredAt": "2025-01-15T13:30:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {
        "name": "Acme Corp"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/members",
    "page": "1",
    "limit": "50",
    "total_results": "12",
    "query": ""
  }
}

organization.list_workos_events

Records when a user views the organization’s audit log events.

Triggered When

User queries the audit log events via the WorkOS events API endpoint.

Event Schema

string

required

organization.list_workos_events

array

required

Show organization target

string

required

organization

string

required

Organization’s unique identifier

string

required

Organization name

string

required

Organization name (duplicated for consistency)

string

required

Page route where events were viewed

string

First chunk of event type filters (comma-separated, max 500 chars)

string

Second chunk of event type filters (if first chunk exceeded 500 chars)

string

Third chunk of event type filters (if second chunk exceeded 500 chars)

string

required

Number of events requested (as string)

string

required

Total number of events returned (as string)

string

Start of date range filter (ISO 8601 timestamp, empty if not specified)

string

End of date range filter (ISO 8601 timestamp, empty if not specified)

string

Pagination cursor for next page (empty if not specified)

Example Event

{
  "action": "organization.list_workos_events",
  "occurredAt": "2025-01-15T15:00:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {
        "name": "Acme Corp"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/logs",
    "events_1": "api_key.create, api_key.revoke, project.create",
    "events_2": "",
    "events_3": "",
    "limit": "100",
    "total_results": "47",
    "range_start": "2025-01-01T00:00:00.000Z",
    "range_end": "2025-01-15T23:59:59.999Z",
    "after": ""
  }
}

Event type filters are split across events_1, events_2, and events_3 fields because WorkOS has a 500-character limit per metadata field. The event types are comma-separated within each chunk.

organization.create_domains_portal_url

Records when an admin generates a URL to access the WorkOS domains management portal.

Triggered When

Admin requests access to the WorkOS self-service domain verification portal.

Event Schema

string

required

organization.create_domains_portal_url

array

required

Show organization target

string

required

organization

string

required

Organization’s unique identifier

string

required

Organization name

string

required

Organization name (duplicated for consistency)

string

required

Page route where portal URL was generated

Example Event

{
  "action": "organization.create_domains_portal_url",
  "occurredAt": "2025-01-15T12:00:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {
        "name": "Acme Corp"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/domains"
  }
}

Projects

Project-level settings and configuration changes

Project Memberships

User access grants and role changes for projects

SSO

Single sign-on configuration for organizations

Directory Sync

Automated user provisioning and directory connections

​organization.create

​Triggered When

​Event Schema

​Example Event

​organization.update_name

​Triggered When

​Event Schema

​Example Event

​organization.view_settings

​Triggered When

​Event Schema

​Example Event

​organization.view_domains

​Triggered When

​Event Schema

​Example Event

​organization.delete_domain

​Triggered When

​Event Schema

​Example Event

​organization.list_memberships

​Triggered When

​Event Schema

​Example Event

​organization.list_workos_events

​Triggered When

​Event Schema

​Example Event

​organization.create_domains_portal_url

​Triggered When

​Event Schema

​Example Event

​Related Events

Projects

Project Memberships

SSO

Directory Sync

organization.create

Triggered When

Event Schema

Example Event

organization.update_name

Triggered When

Event Schema

Example Event

organization.view_settings

Triggered When

Event Schema

Example Event

organization.view_domains

Triggered When

Event Schema

Example Event

organization.delete_domain

Triggered When

Event Schema

Example Event

organization.list_memberships

Triggered When

Event Schema

Example Event

organization.list_workos_events

Triggered When

Event Schema

Example Event

organization.create_domains_portal_url

Triggered When

Event Schema

Example Event

Related Events