@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/events/index.mdx

@@ -0,0 +1,783 @@
+---
+title: Events
+description: "Respond to activity that occurs within WorkOS and third-party\_providers."
+originalPath: .tmp-workos-clone/packages/docs/content/events/index.mdx
+---
+
+Events represent activity that has occurred within WorkOS or within third-party identity and directory providers. Your app can [sync the data](/events/data-syncing) via either the events API or webhooks.
+
+#### Event object
+
+All event objects share a similar structure.
+
+| Attribute    | Description                                                                |
+| ------------ | -------------------------------------------------------------------------- |
+| `event`      | A string that distinguishes the event type.                                |
+| `id`         | Unique identifier for the event.                                           |
+| `data`       | Event payload. Payloads match the corresponding [API objects](/reference). |
+| `created_at` | Timestamp of when the event occurred.                                      |
+
+## Authentication events {{ "url": "authentication" }}
+
+Each step in the [authentication](/reference/user-management/authentication) flow emits an authentication event. Authentication success events are emitted even when additional steps, such as MFA, are required to complete the process.
+
+<Event.Root mt="5">
+  <Event.Details name="authentication.email_verification_failed" comingSoon>
+    <CodeBlock
+      title="Email verification failed event"
+      file="event-authentication-email-verification-failed"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user fails to verify their email.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.email_verification_succeeded">
+    <CodeBlock
+      title="Email verification succeeded event"
+      file="event-authentication-email-verification-succeeded"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully verifies their email.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.magic_auth_failed">
+    <CodeBlock
+      title="Magic Auth failed event"
+      file="event-authentication-magic-auth-failed"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user fails to authenticate via Magic Auth.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.magic_auth_succeeded">
+    <CodeBlock
+      title="Magic Auth succeeded event"
+      file="event-authentication-magic-auth-succeeded"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully authenticates via Magic Auth.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.mfa_failed" comingSoon>
+    <CodeBlock
+      title="MFA failed event"
+      file="event-authentication-mfa-failed"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user fails to authenticate with a multi-factor
+    authentication code.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.mfa_succeeded">
+    <CodeBlock
+      title="MFA succeeded event"
+      file="event-authentication-mfa-succeeded"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully authenticates with a multi-factor
+    authentication code.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.oauth_failed">
+    <CodeBlock
+      title="OAuth failed event"
+      file="event-authentication-oauth-failed"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user fails to authenticate via OAuth.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.oauth_succeeded">
+    <CodeBlock
+      title="OAuth succeeded event"
+      file="event-authentication-oauth-succeeded"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully authenticates via OAuth.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.password_failed">
+    <CodeBlock
+      title="Password authentication failed event"
+      file="event-authentication-password-failed"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user fails to authenticate with password credentials.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.password_succeeded">
+    <CodeBlock
+      title="Password authentication succeeded event"
+      file="event-authentication-password-succeeded"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully authenticates with password credentials.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.passkey_failed">
+    <CodeBlock
+      title="Passkey authentication failed event"
+      file="event-authentication-passkey-failed"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user fails to authenticate with a passkey.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.passkey_succeeded">
+    <CodeBlock
+      title="Passkey authentication succeeded event"
+      file="event-authentication-passkey-succeeded"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully authenticates with a passkey.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.sso_failed">
+    <CodeBlock
+      title="SSO failed event"
+      file="event-authentication-sso-failed"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user fails to authenticate with Single Sign-On.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.sso_succeeded">
+    <CodeBlock
+      title="SSO succeeded event"
+      file="event-authentication-sso-succeeded"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully authenticates with Single Sign-On.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="authentication.radar_risk_detected">
+    <CodeBlock
+      title="Radar risk detected event"
+      file="event-authentication-radar-risk-detected"
+    />
+  </Event.Details>
+  <Event.Description>
+    Triggered when an authentication succeeds but is flagged by Radar. For
+    example, the authentication may have succeeded at passing a Radar challenge.
+  </Event.Description>
+</Event.Root>
+
+## Connection events {{ "url": "connection" }}
+
+Events emitted when Single Sign-On connections are activated, deactivated, or deleted. Also emitted when a SAML certificate is renewed for the connection.
+
+<Event.Root mt="5">
+  <Event.Details name="connection.activated">
+    <CodeBlock
+      title="Connection activated event"
+      file="event-connection-activated"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Connection](/reference/sso/connection)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a connection is activated.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="connection.deactivated">
+    <CodeBlock
+      title="Connection deactivated event"
+      file="event-connection-deactivated"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Connection](/reference/sso/connection)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a connection is deactivated.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="connection.deleted">
+    <CodeBlock
+      title="Connection deleted event"
+      file="event-connection-deleted"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Connection](/reference/sso/connection)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a connection is deleted. The `state` attribute indicates
+    connection state before deletion.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="connection.saml_certificate_renewed">
+    <CodeBlock
+      title="Connection certificate renewed event"
+      file="event-connection-renewed"
+    />
+    <Event.Description>
+      The `certificate_type` can be one of `ResponseSigning`, `RequestSigning`,
+      or `ResponseEncryption`.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a SAML certificate is renewed either in the Dashboard or
+    Admin Portal.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="connection.saml_certificate_renewal_required">
+    <CodeBlock
+      title="Connection certificate renewal required event"
+      file="event-connection-renewal-required"
+    />
+    <Event.Description>
+      The `certificate_type` can be one of `ResponseSigning`, `RequestSigning`,
+      or `ResponseEncryption`.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a SAML certificate is expiring (multiple events are sent out
+    as it approaches expiry), or expired (once every 7 days after expiry).
+  </Event.Description>
+</Event.Root>
+
+## Directory Sync events {{ "url": "directory-sync" }}
+
+Events emitted when directory-related resources are changed. To learn what exactly each of these events represents, see the [in-depth Directory Sync events guide](/directory-sync/understanding-events).
+
+<Event.Root mt="5">
+  <Event.Details name="dsync.activated">
+    <CodeBlock title="Directory activated event" file="event-dsync-activated" />
+    <Event.Description>
+      Payload `data` is based on the
+      [Directory](/reference/directory-sync/directory) object, but the `domain`
+      property is replaced with a `domains` array of [Organization
+      Domain](reference/organization-domain).
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory is
+    activated](/directory-sync/understanding-events/directory-events/dsync-activated).
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.deleted">
+    <CodeBlock title="Directory deleted event" file="event-dsync-deleted" />
+    <Event.Description>
+      Payload `data` is based on the
+      [Directory](/reference/directory-sync/directory) object, except the
+      `domain` property is omitted.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory is
+    deleted](/directory-sync/understanding-events/directory-events/dsync-deleted).
+    The `state` attribute indicates directory state before deletion.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.group.created">
+    <CodeBlock
+      title="Directory group created event"
+      file="event-dsync-group-created"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Directory
+      Group](/reference/directory-sync/directory-group) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory group is
+    created](/directory-sync/understanding-events/directory-group-events/dsync-group-created).
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.group.deleted">
+    <CodeBlock
+      title="Directory group deleted event"
+      file="event-dsync-group-deleted"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Directory
+      Group](/reference/directory-sync/directory-group) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory group is
+    deleted](/directory-sync/understanding-events/directory-group-events/dsync-group-deleted).
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.group.updated">
+    <CodeBlock
+      title="Directory group updated event"
+      file="event-dsync-group-updated"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Directory
+      Group](/reference/directory-sync/directory-group) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory group is
+    updated](/directory-sync/understanding-events/directory-group-events/dsync-group-updated).
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.group.user_added">
+    <CodeBlock
+      title="Directory group user added event"
+      file="event-dsync-group-user-added"
+    />
+    <Event.Description>
+      Payload `data` contains a `user` which corresponds to the [Directory
+      User](/reference/directory-sync/directory-user) object and a `group` which
+      corresponds to the [Directory
+      Group](/reference/directory-sync/directory-group) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory group user is
+    added](/directory-sync/understanding-events/directory-group-events/dsync-group-user-added).
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.group.user_removed">
+    <CodeBlock
+      title="Directory group user removed event"
+      file="event-dsync-group-user-removed"
+    />
+    <Event.Description>
+      Payload `data` contains a `user` which corresponds to the [Directory
+      User](/reference/directory-sync/directory-user) object and a `group` which
+      corresponds to the [Directory
+      Group](/reference/directory-sync/directory-group) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory group user is
+    removed](/directory-sync/understanding-events/directory-group-events/dsync-group-user-removed).
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.user.created">
+    <CodeBlock
+      title="Directory user created event"
+      file="event-dsync-user-created"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Directory
+      User](/reference/directory-sync/directory-user) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory user is
+    created](/directory-sync/understanding-events/directory-user-events/dsync-user-created).
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.user.deleted">
+    <CodeBlock
+      title="Directory user deleted event"
+      file="event-dsync-user-deleted"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Directory
+      User](/reference/directory-sync/directory-user) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory user is
+    deleted](/directory-sync/understanding-events/directory-user-events/dsync-user-deleted).
+    The `state` attribute indicates directory user state at time of deletion.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="dsync.user.updated">
+    <CodeBlock
+      title="Directory user updated event"
+      file="event-dsync-user-updated"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Directory
+      User](/reference/directory-sync/directory-user) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a [directory user is
+    updated](/directory-sync/understanding-events/directory-user-events/dsync-user-updated).
+  </Event.Description>
+</Event.Root>
+
+## Email verification events {{ "url": "email-verification" }}
+
+Events emitted when a user is required to verify their email.
+
+<Event.Root>
+  <Event.Details name="email_verification.created">
+    <CodeBlock
+      title="Email verification created event"
+      file="event-email-verification-created"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Email
+      verification](/user-management/email-verification) object with the `code`
+      omitted.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user is required to verify their email and a code is
+    created.
+  </Event.Description>
+</Event.Root>
+
+## Invitation events {{ "url": "invitation" }}
+
+Events emitted when a [User Management user](/reference/user-management/user) is invited to join an organization.
+
+<Event.Root>
+  <Event.Details name="invitation.created">
+    <CodeBlock
+      title="Invitation created event"
+      file="event-invitation-created"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the
+      [Invitation](/reference/user-management/invitation) object with the
+      `token` omitted.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user is invited to sign up or to join an organization.
+  </Event.Description>
+</Event.Root>
+
+## Magic Auth events {{ "url": "magic-auth" }}
+
+Events emitted when a user requests a Magic Auth code.
+
+<Event.Root>
+  <Event.Details name="magic_auth.created">
+    <CodeBlock
+      title="Magic Auth created event"
+      file="event-magic-auth-created"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Magic
+      Auth](/reference/user-management/magic-auth) object with the `code`
+      omitted.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user initiates Magic Auth and an authentication code is
+    created.
+  </Event.Description>
+</Event.Root>
+
+## Organization events {{ "url": "organization" }}
+
+Events emitted when WorkOS organizations are created, updated, or deleted.
+
+<Event.Root>
+  <Event.Details name="organization.created">
+    <CodeBlock title="Organization created" file="event-organization-created" />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization](/reference/organization)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization is created.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="organization.updated">
+    <CodeBlock title="Organization updated" file="event-organization-updated" />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization](/reference/organization)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization is updated.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="organization.deleted">
+    <CodeBlock title="Organization deleted" file="event-organization-deleted" />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization](/reference/organization)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization is deleted
+  </Event.Description>
+</Event.Root>
+
+## Organization domain events {{ "url": "organization-domain" }}
+
+Events emitted when verification status of an organization domain changes.
+
+<Event.Root mt="5">
+  <Event.Details name="organization_domain.verified">
+    <CodeBlock
+      title="Organization domain verified event"
+      file="event-organization-domain-verified"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization
+      Domain](/reference/domain-verification) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization domain is verified.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="organization_domain.verification_failed">
+    <CodeBlock
+      title="Organization domain verification failed event"
+      file="event-organization-domain-verification-failed"
+    />
+    <Event.Description>
+      Payload `data` contains a `reason` and an `organization_domain` which
+      corresponds to the [Organization Domain](/reference/domain-verification)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization domain verification fails.
+  </Event.Description>
+</Event.Root>
+
+## Organization membership events {{ "url": "organization-membership" }}
+
+Events emitted when a [User Management user](/reference/user-management/user) joins or leaves an organization.
+
+<Event.Root>
+  <Event.Details name="organization_membership.created">
+    <CodeBlock
+      title="Organization membership created event"
+      file="event-membership-created"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization
+      Membership](/reference/user-management/organization-membership) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization membership is created.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="organization_membership.deleted">
+    <CodeBlock
+      title="Organization membership deleted event"
+      file="event-membership-deleted"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization
+      Membership](/reference/user-management/organization-membership) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization membership is deleted.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="organization_membership.updated">
+    <CodeBlock
+      title="Organization membership updated event"
+      file="event-membership-updated"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization
+      Membership](/reference/user-management/organization-membership) object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when an organization membership is updated.
+  </Event.Description>
+</Event.Root>
+
+## Password reset events {{ "url": "password-reset" }}
+
+Events emitted when a user requests to reset their password.
+
+<Event.Root>
+  <Event.Details name="password_reset.created">
+    <CodeBlock
+      title="Password reset created event"
+      file="event-password-reset-created"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Organization
+      Membership](/reference/user-management/password-reset) object with the
+      `token` omitted.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user requests to reset their password.
+  </Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="password_reset.succeeded">
+    <CodeBlock
+      title="Password reset succeeded event"
+      file="event-password-reset-succeeded"
+    />
+    <Event.Description>
+      Payload `data` corresponds to the [Password
+      Reset](/reference/user-management/password-reset) object with the `token`
+      omitted.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>
+    Triggered when a user successfully resets their password.
+  </Event.Description>
+</Event.Root>
+
+## Role events {{ "url": "role" }}
+
+Events emitted when roles are created or deleted in the WorkOS dashboard.
+
+<Event.Root>
+  <Event.Details name="role.created">
+    <CodeBlock title="Role created event" file="event-role-created" />
+  </Event.Details>
+  <Event.Description>Triggered when a role is created.</Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="role.deleted">
+    <CodeBlock title="Role deleted event" file="event-role-deleted" />
+  </Event.Details>
+  <Event.Description>Triggered when a role is deleted.</Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="role.updated">
+    <CodeBlock title="Role updated event" file="event-role-updated" />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a role's permissions are updated.
+  </Event.Description>
+</Event.Root>
+
+## Session events {{ "url": "session" }}
+
+Events emitted when User Management sessions are created.
+
+<Event.Root>
+  <Event.Details name="session.created">
+    <CodeBlock title="Session created event" file="event-session-created" />
+  </Event.Details>
+  <Event.Description>
+    Triggered when a session is created. Sessions started using
+    [impersonation](/user-management/impersonation) will include an additional
+    `impersonator` field with data about the impersonator.
+  </Event.Description>
+</Event.Root>
+
+## User events {{ "url": "user" }}
+
+Events emitted when [User Management users](/reference/user-management/user) are created, updated, or deleted.
+
+<Event.Root>
+  <Event.Details name="user.created">
+    <CodeBlock title="User created event" file="event-user-created" />
+    <Event.Description>
+      Payload `data` corresponds to the [User](/reference/user-management/user)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>Triggered when a user is created.</Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="user.deleted">
+    <CodeBlock title="User deleted event" file="event-user-deleted" />
+    <Event.Description>
+      Payload `data` corresponds to the [User](/reference/user-management/user)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>Triggered when a user is deleted.</Event.Description>
+</Event.Root>
+
+<Event.Root>
+  <Event.Details name="user.updated">
+    <CodeBlock title="User updated event" file="event-user-updated" />
+    <Event.Description>
+      Payload `data` corresponds to the [User](/reference/user-management/user)
+      object.
+    </Event.Description>
+  </Event.Details>
+  <Event.Description>Triggered when a user is updated.</Event.Description>
+</Event.Root>