<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Events

Events represent activity that has occurred within WorkOS or within third-party identity and directory providers. Your app can [sync the data](https://workos.com/docs/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](https://workos.com/docs/reference). |
| `created_at` | Timestamp of when the event occurred.                                      |
| `context`    | An optional object of extra information relevant to the event.             |

## Agent registration events

Events emitted during the agent registration lifecycle, including creation, claim attempts, claim completion, credential issuance, identity assertion refresh, and organization switching.

:::code-group{title="Agent registration claim attempt created event"}

```json language="json"
{
  "object": "event",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWE",
  "event": "agent.registration.claim.attempt.created",
  "data": {
    "object": "agent_registration_claim_attempt",
    "id": "agent_reg_claim_attempt_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "agent_registration_id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "agent_registration_claim_id": "agent_reg_claim_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "login_hint": "jane@example.com",
    "expires_at": "2024-01-15T10:35:00.000Z",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  },
  "created_at": "2024-01-15T10:30:00.000Z"
}
```

:::

<Event.Description>Triggered when a claim attempt is initiated for an agent registration.</Event.Description>

:::code-group{title="Agent registration claim completed event"}

```json language="json"
{
  "object": "event",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWF",
  "event": "agent.registration.claim.completed",
  "data": {
    "object": "agent_registration_claim",
    "id": "agent_reg_claim_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "agent_registration_id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "completed_by_attempt_id": "agent_reg_claim_attempt_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "claimed_by": {
      "user_id": "user_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "organization_id": null
    },
    "completed_at": "2024-01-15T10:32:00.000Z",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:32:00.000Z"
  },
  "created_at": "2024-01-15T10:32:00.000Z"
}
```

:::

<Event.Description>Triggered when an agent registration claim is successfully completed.</Event.Description>

:::code-group{title="Agent registration created event"}

```json language="json"
{
  "object": "event",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWD",
  "event": "agent.registration.created",
  "data": {
    "object": "agent_registration",
    "id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "agent_identity": {
      "object": "agent_identity",
      "id": "agent_identity_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "userland_user_id": null
    },
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "status": "unverified",
    "kind": "anonymous",
    "method": "anonymous",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  },
  "created_at": "2024-01-15T10:30:00.000Z"
}
```

:::

<Event.Description>Triggered when a new agent registration is created.</Event.Description>

:::code-group{title="Agent registration credential issued event"}

```json language="json"
{
  "object": "event",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWG",
  "event": "agent.registration.credential.issued",
  "data": {
    "object": "agent_registration_credential",
    "id": "agent_reg_credential_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "agent_registration_id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "detail": {
      "kind": "api_key",
      "api_key_id": "api_key_01HWDP91J37GZW2FT9GCEX8YWV"
    },
    "created_at": "2024-01-15T10:33:00.000Z",
    "updated_at": "2024-01-15T10:33:00.000Z"
  },
  "created_at": "2024-01-15T10:33:00.000Z"
}
```

:::

<Event.Description>Triggered when a credential is issued for an agent registration.</Event.Description>

:::code-group{title="Agent registration organization switched event"}

```json language="json"
{
  "object": "event",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWH",
  "event": "agent.registration.organization.switched",
  "data": {
    "agent_registration_id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "from_organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "to_organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNZ"
  },
  "created_at": "2024-01-15T10:34:00.000Z"
}
```

:::

<Event.Description>Triggered when an agent registration is moved to a different organization.</Event.Description>

:::code-group{title="Agent registration refreshed event"}

```json language="json"
{
  "object": "event",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWI",
  "event": "agent.registration.refreshed",
  "data": {
    "agent_registration_id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY"
  },
  "created_at": "2024-01-15T10:33:00.000Z"
}
```

:::

<Event.Description>Triggered when an agent registration identity assertion is refreshed.</Event.Description>

## API key events

Events emitted when [API keys](https://workos.com/docs/authkit/api-keys) are created, updated, or revoked.

:::code-group{title="API key created event"}

```json language="json"
{
  "object": "event",
  "id": "event_01KD8Z96BMTAXC8Z9VAQJEYJPW",
  "event": "api_key.created",
  "data": {
    "object": "api_key",
    "id": "api_key_01KD8Z96B7CEWS9F792MVPFZ5X",
    "name": "testing key",
    "owner": {
      "id": "org_01KC5960YS14A61DAEZ30DJ0EG",
      "type": "organization"
    },
    "obfuscated_value": "sk_…kZL1",
    "permissions": ["posts:read"],
    "last_used_at": null,
    "expires_at": null,
    "created_at": "2025-12-24T20:02:23.200Z",
    "updated_at": "2025-12-24T20:02:23.200Z"
  },
  "created_at": "2025-12-24T20:02:23.220Z",
  "context": {}
}
```

:::

<Event.Description>Triggered when an API key is created.</Event.Description>

:::code-group{title="API key revoked event"}

```json language="json"
{
  "object": "event",
  "id": "event_01KD8ZGJK4YWC2WHWHQA71DERV",
  "event": "api_key.revoked",
  "data": {
    "object": "api_key",
    "id": "api_key_01KD8Z96B7CEWS9F792MVPFZ5X",
    "name": "testing key",
    "owner": {
      "id": "org_01KC5960YS14A61DAEZ30DJ0EG",
      "type": "organization"
    },
    "obfuscated_value": "sk_…kZL1",
    "permissions": ["posts:read"],
    "last_used_at": null,
    "expires_at": "2025-12-24T20:02:23.220Z",
    "created_at": "2025-12-24T20:02:23.200Z",
    "updated_at": "2025-12-24T20:02:23.200Z"
  },
  "created_at": "2025-12-24T20:02:23.220Z",
  "context": {}
}
```

:::

<Event.Description>Triggered when an API key is revoked.</Event.Description>

:::code-group{title="API key updated event"}

```json language="json"
{
  "object": "event",
  "id": "event_01KD8ZJ8P66VW2J8YJ9V8KH2RN",
  "event": "api_key.updated",
  "data": {
    "object": "api_key",
    "id": "api_key_01KD8Z96B7CEWS9F792MVPFZ5X",
    "name": "testing key",
    "owner": {
      "id": "org_01KC5960YS14A61DAEZ30DJ0EG",
      "type": "organization"
    },
    "obfuscated_value": "sk_…kZL1",
    "permissions": ["posts:read"],
    "last_used_at": null,
    "expires_at": "2026-01-24T20:02:23.200Z",
    "previous_attributes": {
      "expires_at": null
    },
    "created_at": "2025-12-24T20:02:23.200Z",
    "updated_at": "2025-12-24T20:05:11.420Z"
  },
  "created_at": "2025-12-24T20:05:11.430Z",
  "context": {}
}
```

:::

Triggered when an API key expiration is set, changed, or cleared.

## Authentication events

Each step in the [authentication](https://workos.com/docs/reference/authkit/authentication) flow emits an authentication event. Authentication success events are emitted even when additional steps, such as MFA, are required to complete the process.

:::code-group{title="Email verification failed event"}

```json language="json"
{
  "event": "authentication.email_verification_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "email_verification",
    "status": "failed",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "invalid_one_time_code",
      "message": "Invalid one-time code"
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user fails to verify their email.

:::code-group{title="Email verification succeeded event"}

```json language="json"
{
  "event": "authentication.email_verification_succeeded",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "email_verification",
    "status": "succeeded",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user successfully verifies their email, including when
[accepting an invitation implicitly verifies
it](https://workos.com/docs/authkit/email-verification#users-who-accept-an-invitation).

:::code-group{title="Magic Auth failed event"}

```json language="json"
{
  "event": "authentication.magic_auth_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "magic_auth",
    "status": "failed",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "authentication_method_not_allowed",
      "message": "Google OAuth is disabled."
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user fails to authenticate via Magic Auth.

:::code-group{title="Magic Auth succeeded event"}

```json language="json"
{
  "event": "authentication.magic_auth_succeeded",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "magic_auth",
    "status": "succeeded",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user successfully authenticates via Magic Auth.

:::code-group{title="MFA failed event"}

```json language="json"
{
  "event": "authentication.mfa_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "mfa",
    "status": "failed",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "invalid_one_time_code",
      "message": "Invalid one-time code."
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user fails to authenticate with a multi-factor
authentication code.

:::code-group{title="MFA succeeded event"}

```json language="json"
{
  "event": "authentication.mfa_succeeded",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "mfa",
    "status": "succeeded",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user successfully authenticates with a multi-factor
authentication code.

:::code-group{title="OAuth failed event"}

```json language="json"
{
  "event": "authentication.oauth_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "oauth",
    "status": "failed",
    "provider": "GoogleOAuth",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "invalid_credentials",
      "message": "Invalid credentials."
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user fails to authenticate via OAuth. The payload includes
the OAuth provider used for the attempt.

:::code-group{title="OAuth succeeded event"}

```json language="json"
{
  "event": "authentication.oauth_succeeded",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "oauth",
    "status": "succeeded",
    "provider": "GoogleOAuth",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user successfully authenticates via OAuth. The payload
includes the OAuth provider used for authentication.

:::code-group{title="Password authentication failed event"}

```json language="json"
{
  "event": "authentication.password_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "password",
    "status": "failed",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "invalid_credentials",
      "message": "Invalid credentials."
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user fails to authenticate with password credentials.

:::code-group{title="Password authentication succeeded event"}

```json language="json"
{
  "event": "authentication.password_succeeded",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "password",
    "status": "succeeded",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user successfully authenticates with password credentials.

:::code-group{title="Passkey authentication failed event"}

```json language="json"
{
  "event": "authentication.passkey_failed",
  "id": "event_01HS2EAGQA9EZW6D0MFCV5S38D",
  "data": {
    "type": "passkey",
    "status": "failed",
    "email": "todd@example.com",
    "user_id": "user_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "error": {
      "code": "invalid_credentials",
      "message": "Invalid credentials."
    },
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "ip_address": "0.0.0.0"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user fails to authenticate with a passkey.

:::code-group{title="Passkey authentication succeeded event"}

```json language="json"
{
  "event": "authentication.passkey_succeeded",
  "id": "event_01HS2EAGQA9EZW6D0MFCV5S38D",
  "data": {
    "type": "passkey",
    "status": "succeeded",
    "email": "todd@example.com",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "ip_address": "0.0.0.0",
    "user_id": "user_01EHWNC0FCBHZ3BJ7EGKYXK0E6"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user successfully authenticates with a passkey.

:::code-group{title="SSO started event"}

```json language="json"
{
  "event": "authentication.sso_started",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "sso",
    "status": "started",
    "user_id": null,
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "sso": {
      "connection_id": "conn_01FKJ843CVE8F7BXQSPFH0M53V",
      "organization_id": "org_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
      "session_id": "saml_session_01FKJ843CVE8F7BXQSPFH0M53V"
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a Single Sign-On session starts. For a session your
application starts, this is before the user is sent to the identity
provider, and `email` is the `login_hint` the application supplied, when
one was provided, typically the address the user entered to start the
sign-in. The identity provider has not verified it yet, and `user_id` is
not known at this point. For a session the identity
provider starts, the event is emitted when its response arrives and carries
no email.

:::code-group{title="SSO failed event"}

```json language="json"
{
  "event": "authentication.sso_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "sso",
    "status": "failed",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "authentication_method_not_allowed",
      "message": "SSO is disabled for this environment."
    },
    "sso": {
      "connection_id": "conn_01FKJ843CVE8F7BXQSPFH0M53V",
      "organization_id": "org_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E"
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user fails to authenticate with Single Sign-On.

:::code-group{title="SSO succeeded event"}

```json language="json"
{
  "event": "authentication.sso_succeeded",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "sso",
    "status": "succeeded",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "sso": {
      "connection_id": "conn_01FKJ843CVE8F7BXQSPFH0M53V",
      "organization_id": "org_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
      "session_id": "saml_session_01FKJ843CVE8F7BXQSPFH0M53V"
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a user successfully authenticates with Single Sign-On.

:::code-group{title="Radar risk detected event"}

```json language="json"
{
  "event": "authentication.radar_risk_detected",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "auth_method": "magic_auth",
    "action": "signup",
    "control": "restriction",
    "blocklist_type": "ip_address",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when an authentication succeeds but is flagged by Radar. For
example, the authentication may have succeeded at passing a Radar challenge.

## Connection events

Events emitted when Single Sign-On connections are activated, deactivated, or deleted. Also emitted when a SAML certificate is renewed for the connection.

:::code-group{title="Connection activated event"}

```json language="json"
{
  "event": "connection.activated",
  "id": "event_10FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "connection",
    "id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "state": "active",
    "connection_type": "OktaSAML",
    "name": "Foo Corp's Connection",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "id": "org_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
        "object": "connection_domain",
        "domain": "foo-corp.com"
      }
    ]
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Connection](https://workos.com/docs/reference/sso/connection)
object.

Triggered when a connection is activated.

:::code-group{title="Connection deactivated event"}

```json language="json"
{
  "event": "connection.deactivated",
  "id": "event_11FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "connection",
    "id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "state": "inactive",
    "connection_type": "OktaSAML",
    "name": "Foo Corp's Connection",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "id": "org_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
        "object": "connection_domain",
        "domain": "foo-corp.com"
      }
    ]
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Connection](https://workos.com/docs/reference/sso/connection)
object.

Triggered when a connection is deactivated.

:::code-group{title="Connection deleted event"}

```json language="json"
{
  "event": "connection.deleted",
  "id": "event_12FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "connection",
    "id": "conn_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "state": "inactive",
    "connection_type": "OktaSAML",
    "name": "Foo Corp's Connection",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "id": "org_domain_01EHWNFTAFCF3CQAE5A9Q0P1YB",
        "object": "connection_domain",
        "domain": "foo-corp.com"
      }
    ]
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Connection](https://workos.com/docs/reference/sso/connection)
object.

Triggered when a connection is deleted. The `state` attribute indicates
connection state before deletion.

:::code-group{title="Connection certificate renewed event"}

```json language="json"
{
  "event": "connection.saml_certificate_renewed",
  "id": "event_12FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "connection": {
      "id": "conn_12FKJ843CVE8F7BXQSPFH0M53V",
      "organization_id": "org_12FKJ843CVE8F7BXQSPFH0M53V"
    },
    "certificate": {
      "certificate_type": "ResponseSigning",
      "expiry_date": "2025-06-28T19:07:33.155Z"
    },
    "renewed_at": "2021-06-25T19:07:33.155Z"
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

The `certificate_type` can be one of `ResponseSigning`, `RequestSigning`,
or `ResponseEncryption`.

Triggered when a SAML certificate is renewed either in the Dashboard or
Admin Portal.

:::code-group{title="Connection certificate renewal required event"}

```json language="json"
{
  "event": "connection.saml_certificate_renewal_required",
  "id": "event_12FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "connection": {
      "id": "conn_12FKJ843CVE8F7BXQSPFH0M53V",
      "organization_id": "org_12FKJ843CVE8F7BXQSPFH0M53V"
    },
    "certificate": {
      "certificate_type": "ResponseSigning",
      "expiry_date": "2021-06-28T19:07:33.155Z",
      "is_expired": false
    },
    "days_until_expiry": 3
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

The `certificate_type` can be one of `ResponseSigning`, `RequestSigning`,
or `ResponseEncryption`.

Triggered when a SAML certificate is expiring (multiple events are sent out
as it approaches expiry), or expired (once every 7 days after expiry).

## Directory Sync events

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](https://workos.com/docs/directory-sync/understanding-events).

:::code-group{title="Directory activated event"}

```json language="json"
{
  "event": "dsync.activated",
  "id": "event_01FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "directory",
    "external_key": "UWuccu6o1E0GqkYs",
    "name": "Foo Corp's Directory",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "id": "directory_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "state": "active",
    "type": "generic scim v2.0",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "domains": [
      {
        "object": "organization_domain",
        "id": "org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6",
        "domain": "foo-corp.com"
      }
    ]
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` is based on the
[Directory](https://workos.com/docs/reference/directory-sync/directory) object, but the `domain`
property is replaced with a `domains` array of [Organization
Domain](https://workos.com/docs/reference/domain-verification).

Triggered when a [directory is
activated](https://workos.com/docs/directory-sync/understanding-events/directory-events/dsync-activated).

:::code-group{title="Directory deleted event"}

```json language="json"
{
  "event": "dsync.deleted",
  "id": "event_03FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "directory",
    "id": "directory_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "type": "generic scim v2.0",
    "state": "deleting",
    "name": "Foo Corp's Directory",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z"
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` is based on the
[Directory](https://workos.com/docs/reference/directory-sync/directory) object, except the
`domain` property is omitted.

Triggered when a [directory is
deleted](https://workos.com/docs/directory-sync/understanding-events/directory-events/dsync-deleted).
The `state` attribute indicates directory state before deletion.

:::code-group{title="Directory group created event"}

```json language="json"
{
  "event": "dsync.group.created",
  "id": "event_44FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "name": "Developers",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z"
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Directory
Group](https://workos.com/docs/reference/directory-sync/directory-group) object.

Triggered when a [directory group is
created](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-created).

:::code-group{title="Directory group deleted event"}

```json language="json"
{
  "event": "dsync.group.deleted",
  "id": "event_06FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "name": "Developers",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z"
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Directory
Group](https://workos.com/docs/reference/directory-sync/directory-group) object.

Triggered when a [directory group is
deleted](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-deleted).

:::code-group{title="Directory group updated event"}

```json language="json"
{
  "event": "dsync.group.updated",
  "id": "event_54FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
    "idp_id": "02grqrue4294w24",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "name": "Developers",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "previous_attributes": {}
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Directory
Group](https://workos.com/docs/reference/directory-sync/directory-group) object.

Triggered when a [directory group is
updated](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-updated).

:::code-group{title="Directory group user added event"}

```json language="json"
{
  "event": "dsync.group.user_added",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "user": {
      "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "idp_id": "2936",
      "email": "eric@example.com",
      "first_name": "Eric",
      "last_name": "Schneider",
      "name": "Eric Schneider",
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "custom_attributes": {
        "emails": [
          {
            "primary": true,
            "type": "work",
            "value": "eric@example.com"
          }
        ],
        "department": "Engineering",
        "job_title": "Software Engineer",
        "username": "eric@example.com"
      },
      "role": { "slug": "member" },
      "roles": [{ "slug": "member" }]
    },
    "group": {
      "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
      "idp_id": "02grqrue4294w24",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "name": "Developers",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z"
    }
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` contains a `user` which corresponds to the [Directory
User](https://workos.com/docs/reference/directory-sync/directory-user) object and a `group` which
corresponds to the [Directory
Group](https://workos.com/docs/reference/directory-sync/directory-group) object. The `groups`
field is omitted from the `user` object to avoid performance issues in
large directories.

Triggered when a [directory group user is
added](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-user-added).

:::code-group{title="Directory group user removed event"}

```json language="json"
{
  "event": "dsync.group.user_removed",
  "id": "event_05FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "user": {
      "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "idp_id": "2936",
      "email": "eric@example.com",
      "first_name": "Eric",
      "last_name": "Schneider",
      "name": "Eric Schneider",
      "state": "active",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "custom_attributes": {
        "emails": [
          {
            "primary": true,
            "type": "work",
            "value": "eric@example.com"
          }
        ],
        "department": "Engineering",
        "job_title": "Software Engineer",
        "username": "eric@example.com"
      },
      "role": { "slug": "member" },
      "roles": [{ "slug": "member" }]
    },
    "group": {
      "id": "directory_group_01E1X5GPMMXF4T1DCERMVEEPVW",
      "idp_id": "02grqrue4294w24",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "name": "Developers",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z"
    }
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` contains a `user` which corresponds to the [Directory
User](https://workos.com/docs/reference/directory-sync/directory-user) object and a `group` which
corresponds to the [Directory
Group](https://workos.com/docs/reference/directory-sync/directory-group) object. The `groups`
field is omitted from the `user` object to avoid performance issues in
large directories.

Triggered when a [directory group user is
removed](https://workos.com/docs/directory-sync/understanding-events/directory-group-events/dsync-group-user-removed).

:::code-group{title="Directory user created event"}

```json language="json"
{
  "event": "dsync.user.created",
  "id": "event_07FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "email": "lela.block@example.com",
    "first_name": "Lela",
    "last_name": "Block",
    "name": "Lela Block",
    "state": "active",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "emails": [
        {
          "primary": true,
          "type": "work",
          "value": "lela.block@example.com"
        }
      ],
      "department": "Engineering",
      "job_title": "Software Engineer",
      "username": "lela.block@example.com"
    },
    "role": { "slug": "member" },
    "roles": [{ "slug": "member" }]
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Directory
User](https://workos.com/docs/reference/directory-sync/directory-user) object. The `groups` field
is omitted to avoid performance issues in large directories.

Triggered when a [directory user is
created](https://workos.com/docs/directory-sync/understanding-events/directory-user-events/dsync-user-created).

:::code-group{title="Directory user deleted event"}

```json language="json"
{
  "event": "dsync.user.deleted",
  "id": "event_09FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "email": "lela.block@example.com",
    "first_name": "Lela",
    "last_name": "Block",
    "name": "Lela Block",
    "state": "inactive",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "emails": [
        {
          "primary": true,
          "type": "work",
          "value": "lela.block@example.com"
        }
      ],
      "department": "Engineering",
      "job_title": "Software Engineer",
      "username": "lela.block@example.com"
    },
    "role": { "slug": "member" },
    "roles": [{ "slug": "member" }]
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Directory
User](https://workos.com/docs/reference/directory-sync/directory-user) object. The `groups` field
is omitted to avoid performance issues in large directories.

Triggered when a [directory user is
deleted](https://workos.com/docs/directory-sync/understanding-events/directory-user-events/dsync-user-deleted).
The `state` attribute indicates directory user state at time of deletion.

:::code-group{title="Directory user updated event"}

```json language="json"
{
  "event": "dsync.user.updated",
  "id": "event_08FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "email": "lela.block@example.com",
    "first_name": "Lela",
    "last_name": "Block",
    "name": "Lela Block",
    "state": "active",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "emails": [
        {
          "primary": true,
          "type": "work",
          "value": "lela.block@example.com"
        }
      ],
      "department": "Engineering",
      "job_title": "Software Engineer",
      "username": "lela.block@example.com"
    },
    "role": { "slug": "member" },
    "roles": [{ "slug": "member" }],
    "previous_attributes": {}
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Directory
User](https://workos.com/docs/reference/directory-sync/directory-user) object. The `groups` field
is omitted to avoid performance issues in large directories.

Triggered when a [directory user is
updated](https://workos.com/docs/directory-sync/understanding-events/directory-user-events/dsync-user-updated).

## Email verification events

Events emitted when a user is required to verify their email.

:::code-group{title="Email verification created event"}

```json language="json"
{
  "event": "email_verification.created",
  "id": "event_01HYGAQ6DVKP4TKDF8P8AHFP47",
  "data": {
    "object": "email_verification",
    "id": "email_verification_01HYGAQN7DTHPWDDMMTW6GRN4Z",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "expires_at": "2023-11-16T21:32:25.235Z",
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the [Email
verification](https://workos.com/docs/authkit/email-verification) object with the `code` omitted.

Triggered when a user is required to verify their email and a code is
created. This event is not emitted when [accepting an invitation implicitly
verifies the email](https://workos.com/docs/authkit/email-verification#users-who-accept-an-invitation),
since no code is created.

## Feature flag events

Events emitted when WorkOS feature flags are created, updated, or deleted, and when a flag's rules or targets change in an environment.

:::code-group{title="Feature flag created event"}

```json language="json"
{
  "event": "feature_flags.flag.created",
  "id": "event_01K43DMGDK941Z4YPH6XGHTY3S",
  "data": {
    "object": "feature_flag",
    "id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "slug": "advanced-audit-logging",
    "name": "Advanced Audit Logging",
    "description": "Enables the advanced audit log export.",
    "owner": {
      "email": "tom@example.com",
      "first_name": "Tom",
      "last_name": "Kim"
    },
    "tags": [
      "enterprise"
    ],
    "enabled": false,
    "default_value": false,
    "created_at": "2026-10-01T17:56:30.985Z",
    "updated_at": "2026-10-01T17:56:30.985Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    }
  },
  "created_at": "2026-10-01T17:56:31.027Z"
}
```

:::

Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags)
object in the environment the event was sent for.

Triggered when a feature flag is created. One event is sent for each
environment.

:::code-group{title="Feature flag updated event"}

```json language="json"
{
  "event": "feature_flags.flag.updated",
  "id": "event_01K43DTR8V2N6Q4M0K1J3H5G7F",
  "data": {
    "object": "feature_flag",
    "id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "slug": "advanced-audit-logging",
    "name": "Advanced Audit Logging",
    "description": "Enables the advanced audit log export.",
    "owner": {
      "email": "tom@example.com",
      "first_name": "Tom",
      "last_name": "Kim"
    },
    "tags": [
      "enterprise"
    ],
    "enabled": true,
    "default_value": false,
    "created_at": "2026-10-01T17:56:30.985Z",
    "updated_at": "2026-10-01T18:04:11.402Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    },
    "previous_attributes": {
      "data": {
        "enabled": false
      }
    }
  },
  "created_at": "2026-10-01T18:04:11.455Z"
}
```

:::

Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags)
object in the environment the event was sent for.
`context.previous_attributes.data` holds the previous values of the fields
that changed.

Triggered when a feature flag's name, description, owner, or tags change, or
when it is turned on or off or its default value changes in an environment.
A change to the name, description, owner, or tags sends one event for each
environment.

:::code-group{title="Feature flag deleted event"}

```json language="json"
{
  "event": "feature_flags.flag.deleted",
  "id": "event_01K44A7C9E1G3J5K7M9N1P3Q5R",
  "data": {
    "object": "feature_flag",
    "id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "slug": "advanced-audit-logging",
    "name": "Advanced Audit Logging",
    "description": "Enables the advanced audit log export.",
    "owner": {
      "email": "tom@example.com",
      "first_name": "Tom",
      "last_name": "Kim"
    },
    "tags": [
      "enterprise"
    ],
    "enabled": true,
    "default_value": false,
    "created_at": "2026-10-01T17:56:30.985Z",
    "updated_at": "2026-10-01T18:04:11.402Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    }
  },
  "created_at": "2026-10-03T14:22:51.218Z"
}
```

:::

Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags)
object as it was before deletion.

Triggered when a feature flag is deleted. One event is sent for each
environment.

:::code-group{title="Feature flag rule created event"}

```json language="json"
{
  "event": "feature_flags.flag_rule.created",
  "id": "event_01K43E0P7T9V1W3X5Y7Z9A1B3C",
  "data": {
    "object": "flag_rule",
    "id": "flag_rule_01K43E0P6S8T2V4W6X8Y0Z2A4B",
    "flag_id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "flag_slug": "advanced-audit-logging",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "target_type": "organization",
    "position": 0,
    "value_type": "boolean",
    "value": true,
    "created_at": "2026-10-02T09:12:04.311Z",
    "updated_at": "2026-10-02T09:12:04.311Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    }
  },
  "created_at": "2026-10-02T09:12:04.360Z"
}
```

:::

Payload `data` is the rule: the type of target it matches, its zero-based
`position` in evaluation order, and the `value` it serves.

Triggered when a rule is added to a feature flag in an environment. Adding a
target can also create a rule, for example when the first organization is
added to a flag in an environment.

:::code-group{title="Feature flag rule updated event"}

```json language="json"
{
  "event": "feature_flags.flag_rule.updated",
  "id": "event_01K43E5H2K4M6N8P0Q2R4S6T8V",
  "data": {
    "object": "flag_rule",
    "id": "flag_rule_01K43E0P6S8T2V4W6X8Y0Z2A4B",
    "flag_id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "flag_slug": "advanced-audit-logging",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "target_type": "organization",
    "position": 0,
    "value_type": "boolean",
    "value": false,
    "created_at": "2026-10-02T09:12:04.311Z",
    "updated_at": "2026-10-02T09:30:47.126Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    },
    "previous_attributes": {
      "data": {
        "value": true
      }
    }
  },
  "created_at": "2026-10-02T09:30:47.171Z"
}
```

:::

Payload `data` is the rule after the change. When the served value
changed, `context.previous_attributes.data.value` holds the previous
value.

Triggered when a rule's served value or position changes, including when
another rule is added, removed, or moved ahead of it.

:::code-group{title="Feature flag rule deleted event"}

```json language="json"
{
  "event": "feature_flags.flag_rule.deleted",
  "id": "event_01K43F2B4D6F8H0J2K4M6N8P0Q",
  "data": {
    "object": "flag_rule",
    "id": "flag_rule_01K43E0P6S8T2V4W6X8Y0Z2A4B",
    "flag_id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "flag_slug": "advanced-audit-logging",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "target_type": "organization",
    "position": 0,
    "value_type": "boolean",
    "value": false,
    "created_at": "2026-10-02T09:12:04.311Z",
    "updated_at": "2026-10-02T09:30:47.126Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    }
  },
  "created_at": "2026-10-02T10:05:13.904Z"
}
```

:::

Payload `data` is the rule as it was before deletion.

Triggered when a rule is removed from a feature flag in an environment. A
`feature_flags.flag.deleted` event also means the flag's rules were removed,
without this event for each of them.

:::code-group{title="Feature flag target created event"}

```json language="json"
{
  "event": "feature_flags.flag_target.created",
  "id": "event_01K43E1A4D6F8H0J2K4M6N8P0R",
  "data": {
    "object": "flag_target",
    "id": "flag_target_01K43E1A3C5E7G9J1K3M5N7P9Q",
    "flag_id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "flag_slug": "advanced-audit-logging",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "target_type": "organization",
    "target_id": "org_01K1C52WNZ2CR3A9QYHHVWXYZ1",
    "rule_id": "flag_rule_01K43E0P6S8T2V4W6X8Y0Z2A4B",
    "created_at": "2026-10-02T09:12:04.311Z",
    "updated_at": "2026-10-02T09:12:04.311Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    }
  },
  "created_at": "2026-10-02T09:12:04.362Z"
}
```

:::

Payload `data` identifies the flag, the environment, the target, and the
`rule_id` of the rule the target was added to.

Triggered when a user, organization, or custom target is added to a feature
flag rule. One event is sent for each target.

:::code-group{title="Feature flag target deleted event"}

```json language="json"
{
  "event": "feature_flags.flag_target.deleted",
  "id": "event_01K43EZ9X1Z3B5D7F9H1K3M5P7",
  "data": {
    "object": "flag_target",
    "id": "flag_target_01K43E1A3C5E7G9J1K3M5N7P9Q",
    "flag_id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "flag_slug": "advanced-audit-logging",
    "environment_id": "environment_01K43DGP2ZQ8G5TQ3R5V7XB4E1",
    "target_type": "organization",
    "target_id": "org_01K1C52WNZ2CR3A9QYHHVWXYZ1",
    "rule_id": "flag_rule_01K43E0P6S8T2V4W6X8Y0Z2A4B",
    "created_at": "2026-10-02T09:12:04.311Z",
    "updated_at": "2026-10-02T09:12:04.311Z"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    }
  },
  "created_at": "2026-10-02T09:58:36.540Z"
}
```

:::

Payload `data` identifies the flag, the environment, the target, and the
`rule_id` of the rule the target was removed from.

Triggered when a target is removed from a feature flag rule. One event is
sent for each target. A `feature_flags.flag_rule.deleted` or
`feature_flags.flag.deleted` event also means the rule's or flag's targets
were removed, without this event for each of them.

:::code-group{title="Feature flag created event"}

```json language="json"
{
  "event": "flag.created",
  "id": "event_01K43DMGDK941Z4YPH6XGHTY3S",
  "data": {
    "id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "name": "Advanced Audit Logging",
    "slug": "advanced-audit-logging",
    "object": "flag",
    "created_at": "2025-08-28T17:56:30.985Z",
    "updated_at": "2025-08-28T17:56:30.985Z",
    "description": ""
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K9ZXY7Q2W8V5LJ3T4B8N6M5",
      "name": "Colin Morikawa",
      "source": "dashboard"
    }
  },
  "created_at": "2025-08-28T17:56:31.027Z"
}
```

:::

Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags)
object.

Deprecated. Use `feature_flags.flag.created` instead. Triggered when a
feature flag is created.

:::code-group{title="Feature flag updated event"}

```json language="json"
{
  "event": "flag.updated",
  "id": "event_01K43DS82YTHC4BN2J0F6QNVW1",
  "data": {
    "id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "name": "Advanced Audit Logging",
    "slug": "advanced-audit-logging",
    "object": "flag",
    "created_at": "2025-08-28T17:56:30.985Z",
    "updated_at": "2025-09-01T15:49:06.300Z",
    "description": "Enable advanced audit logging for users",
    "tags": ["audit", "logging", "beta"]
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K9ZXY7Q2W8V5LJ3T4B8N6M5",
      "name": "Colin Morikawa",
      "source": "dashboard"
    },
    "previous_attributes": {
      "description": "",
      "tags": ["audit", "logging"]
    }
  },
  "created_at": "2025-09-01T15:49:06.334Z"
}
```

:::

Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags)
object.

Deprecated. Use `feature_flags.flag.updated` instead. Triggered when a
feature flag is updated.

:::code-group{title="Feature flag deleted event"}

```json language="json"
{
  "event": "flag.deleted",
  "id": "event_01K43DMGDK941Z4YPH6XGHTY3S",
  "data": {
    "id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "name": "Advanced Audit Logging",
    "slug": "advanced-audit-logging",
    "object": "flag",
    "created_at": "2025-08-28T17:56:30.985Z",
    "updated_at": "2025-08-28T17:56:30.985Z",
    "description": "Improved logging for audit trail"
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K9ZXY7Q2W8V5LJ3T4B8N6M5",
      "name": "Colin Morikawa",
      "source": "dashboard"
    }
  },
  "created_at": "2025-08-28T17:56:31.027Z"
}
```

:::

Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags)
object.

Deprecated. Use `feature_flags.flag.deleted` instead. Triggered when a
feature flag is deleted.

:::code-group{title="Feature flag rule updated event"}

```json language="json"
{
  "event": "flag.rule_updated",
  "id": "event_01K43DV45EXDX2M6M903MHYHP3",
  "data": {
    "id": "flag_01K43DMGCCK0STXE0EJT2AHQN0",
    "name": "Advanced Audit Logging",
    "slug": "advanced-audit-logging",
    "object": "feature_flag",
    "created_at": "2025-08-28T17:56:30.985Z",
    "updated_at": "2025-08-28T17:56:30.985Z",
    "description": ""
  },
  "context": {
    "client_id": "client_07FA3DZGSL941Z4YPH6XGHTY3S",
    "actor": {
      "id": "user_01K1C557F5P0P36MJ1HE3GRXBN",
      "name": "Tom Kim",
      "source": "dashboard"
    },
    "access_type": "some",
    "configured_targets": {
      "organizations": [
        { "id": "org_01K1C52WNZ2CR3A9QYHHVWXYZ1", "name": "Acme Corp" },
        { "id": "org_01K1C52WNZ2CR3A9QYHHVWXYZ2", "name": "Globex Inc" }
      ],
      "users": []
    },
    "previous_attributes": {
      "context": {
        "access_type": "none",
        "configured_targets": {
          "organizations": [],
          "users": []
        }
      }
    }
  },
  "created_at": "2025-09-01T20:00:07.854Z"
}
```

:::

Payload `data` corresponds to the [Feature Flag](https://workos.com/docs/reference/feature-flags)
object.

Deprecated. Use `feature_flags.flag.updated` when a flag is turned on or off
or its default value changes, and the `feature_flags.flag_rule.*` and
`feature_flags.flag_target.*` events when its targeting changes. Triggered
when a feature flag's rules are modified.

## Group events

Events emitted when [groups](https://workos.com/docs/authkit/groups) are created, updated, deleted, or their members change.

:::code-group{title="Group created event"}

```json language="json"
{
  "event": "group.created",
  "id": "event_01EHZNVPK3SFK441A1RGBFSHRT",
  "data": {
    "object": "group",
    "id": "group_01HXYZ123456789ABCDEFGHIJ",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "name": "Engineering",
    "description": "The engineering team",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "context": {},
  "created_at": "2026-01-15T12:00:00.000Z"
}
```

:::

Payload `data` corresponds to the [Group](https://workos.com/docs/reference/groups) object.

<Event.Description>Triggered when a group is created.</Event.Description>

:::code-group{title="Group updated event"}

```json language="json"
{
  "event": "group.updated",
  "id": "event_01EHZNVPK3SFK441A1RGBFSHRT",
  "data": {
    "object": "group",
    "id": "group_01HXYZ123456789ABCDEFGHIJ",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "name": "Engineering",
    "description": "The engineering team",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-20T09:30:00.000Z"
  },
  "context": {},
  "created_at": "2026-01-20T09:30:00.000Z"
}
```

:::

Payload `data` corresponds to the [Group](https://workos.com/docs/reference/groups) object.

<Event.Description>Triggered when a group is updated.</Event.Description>

:::code-group{title="Group deleted event"}

```json language="json"
{
  "event": "group.deleted",
  "id": "event_01EHZNVPK3SFK441A1RGBFSHRT",
  "data": {
    "object": "group",
    "id": "group_01HXYZ123456789ABCDEFGHIJ",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "name": "Engineering",
    "description": "The engineering team",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "context": {},
  "created_at": "2026-01-25T15:45:00.000Z"
}
```

:::

Payload `data` corresponds to the [Group](https://workos.com/docs/reference/groups) object.

<Event.Description>Triggered when a group is deleted.</Event.Description>

:::code-group{title="Group member added event"}

```json language="json"
{
  "event": "group.member_added",
  "id": "event_01EHZNVPK3SFK441A1RGBFSHRT",
  "data": {
    "group_id": "group_01HXYZ123456789ABCDEFGHIJ",
    "organization_membership_id": "om_01EHWNCE74X7JSDV0X3SZ3KJNY"
  },
  "context": {},
  "created_at": "2026-01-15T12:00:00.000Z"
}
```

:::

Payload `data` contains the `group_id` and `organization_membership_id` of
the added member.

Triggered when an organization membership is added to a group.

:::code-group{title="Group member removed event"}

```json language="json"
{
  "event": "group.member_removed",
  "id": "event_01EHZNVPK3SFK441A1RGBFSHRT",
  "data": {
    "group_id": "group_01HXYZ123456789ABCDEFGHIJ",
    "organization_membership_id": "om_01EHWNCE74X7JSDV0X3SZ3KJNY"
  },
  "context": {},
  "created_at": "2026-01-15T12:00:00.000Z"
}
```

:::

Payload `data` contains the `group_id` and `organization_membership_id` of
the removed member.

Triggered when an organization membership is removed from a group.

## Invitation events

Events emitted when an [AuthKit user](https://workos.com/docs/reference/authkit/user) is invited to join an organization.

:::code-group{title="Invitation accepted event"}

```json language="json"
{
  "event": "invitation.accepted",
  "id": "event_01HWWSM92W0M1GE0DV8BZS00E5",
  "data": {
    "object": "invitation",
    "id": "invitation_01HWWSMMQSP0FAN9PF071E77W9",
    "email": "todd@example.com",
    "state": "accepted",
    "accepted_at": "2023-11-16T21:32:25.235Z",
    "revoked_at": null,
    "expires_at": "2023-11-23T21:32:25.235Z",
    "organization_id": "org_01HWWSSTF0QKDCXMZC911T8BTG",
    "inviter_user_id": "user_01HYGAVW79Z32XVDXZJV0WM6Y9",
    "accepted_user_id": "user_01HYGAVW79Z32XVDXZJV0WM6Y9",
    "role_slug": "admin",
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T22:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the
[Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and
`accept_invitation_url` omitted.

Triggered when a user accepts an invitation.

:::code-group{title="Invitation created event"}

```json language="json"
{
  "event": "invitation.created",
  "id": "event_01HWWSM92W0M1GE0DV8BZS00E5",
  "data": {
    "object": "invitation",
    "id": "invitation_01HWWSMMQSP0FAN9PF071E77W9",
    "email": "todd@example.com",
    "state": "pending",
    "accepted_at": null,
    "revoked_at": null,
    "expires_at": "2023-11-23T21:32:25.235Z",
    "organization_id": "org_01HWWSSTF0QKDCXMZC911T8BTG",
    "inviter_user_id": "user_01HYGAVW79Z32XVDXZJV0WM6Y9",
    "accepted_user_id": null,
    "role_slug": "admin",
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T21:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the
[Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and
`accept_invitation_url` omitted.

Triggered when a user is invited to sign up or to join an organization.

:::code-group{title="Invitation resent event"}

```json language="json"
{
  "event": "invitation.resent",
  "id": "event_01HWWSM92W0M1GE0DV8BZS00E5",
  "data": {
    "object": "invitation",
    "id": "invitation_01HWWSMMQSP0FAN9PF071E77W9",
    "email": "todd@example.com",
    "state": "pending",
    "accepted_at": null,
    "revoked_at": null,
    "expires_at": "2023-11-23T21:32:25.235Z",
    "organization_id": "org_01HWWSSTF0QKDCXMZC911T8BTG",
    "inviter_user_id": "user_01HYGAVW79Z32XVDXZJV0WM6Y9",
    "accepted_user_id": null,
    "role_slug": "admin",
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T22:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the
[Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and
`accept_invitation_url` omitted.

<Event.Description>Triggered when an invitation is resent.</Event.Description>

:::code-group{title="Invitation revoked event"}

```json language="json"
{
  "event": "invitation.revoked",
  "id": "event_01HWWSM92W0M1GE0DV8BZS00E5",
  "data": {
    "object": "invitation",
    "id": "invitation_01HWWSMMQSP0FAN9PF071E77W9",
    "email": "todd@example.com",
    "state": "revoked",
    "accepted_at": null,
    "revoked_at": "2023-11-16T21:32:25.235Z",
    "expires_at": "2023-11-23T21:32:25.235Z",
    "organization_id": "org_01HWWSSTF0QKDCXMZC911T8BTG",
    "inviter_user_id": "user_01HYGAVW79Z32XVDXZJV0WM6Y9",
    "accepted_user_id": null,
    "role_slug": "admin",
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T22:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the
[Invitation](https://workos.com/docs/reference/authkit/invitation) object with the `token` and
`accept_invitation_url` omitted.

Triggered when an invitation is revoked.

## Magic Auth events

Events emitted when a user requests a Magic Auth code.

:::code-group{title="Magic Auth created event"}

```json language="json"
{
  "event": "magic_auth.created",
  "id": "event_01HWWSTZVFADJG9M9EJMKXB043",
  "data": {
    "object": "magic_auth",
    "id": "magic_auth_01HWWSVXCRMA5481VK9601SKQX",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "expires_at": "2023-11-16T21:32:25.235Z",
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the [Magic
Auth](https://workos.com/docs/reference/authkit/magic-auth) object with the `code` omitted.

Triggered when a user initiates Magic Auth and an authentication code is
created.

## Organization events

Events emitted when WorkOS organizations are created, updated, or deleted.

:::code-group{title="Organization created"}

```json language="json"
{
  "event": "organization.created",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
  "data": {
    "id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
    "name": "Foo Corp",
    "object": "organization",
    "external_id": null,
    "domains": [
      {
        "id": "org_domain_01HV1VX5N18E48ETTHNNK54R6S",
        "state": "verified",
        "domain": "foo-corp.com",
        "object": "organization_domain",
        "organization_id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
        "verification_strategy": "manual",
        "verification_prefix": "superapp-domain-verification-z3kjny",
        "verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
        "created_at": "2023-11-27T19:07:33.155Z",
        "updated_at": "2023-11-27T19:07:33.155Z"
      }
    ],
    "metadata": {
      "tier": "diamond"
    },
    "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
    "created_at": "2023-11-16T16:32:25.239Z",
    "updated_at": "2023-11-16T16:32:25.239Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization](https://workos.com/docs/reference/organization)
object.

Triggered when an organization is created.

:::code-group{title="Organization updated"}

```json language="json"
{
  "event": "organization.updated",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
  "data": {
    "id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
    "name": "Foo Corp",
    "object": "organization",
    "external_id": null,
    "domains": [
      {
        "id": "org_domain_01HV1VX5N18E48ETTHNNK54R6S",
        "state": "verified",
        "domain": "foo-corp.com",
        "object": "organization_domain",
        "organization_id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
        "verification_strategy": "manual",
        "verification_prefix": null,
        "verification_token": null,
        "created_at": "2023-11-27T19:07:33.155Z",
        "updated_at": "2023-11-27T19:07:33.155Z"
      }
    ],
    "metadata": {
      "tier": "diamond"
    },
    "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
    "created_at": "2023-11-16T16:32:25.239Z",
    "updated_at": "2023-11-16T17:32:25.239Z"
  },
  "created_at": "2023-11-16T17:32:25.239Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization](https://workos.com/docs/reference/organization)
object.

Triggered when an organization is updated.

:::code-group{title="Organization deleted"}

```json language="json"
{
  "event": "organization.deleted",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
  "data": {
    "id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
    "name": "Foo Corp",
    "object": "organization",
    "external_id": null,
    "domains": [
      {
        "id": "org_domain_01HV1VX5N18E48ETTHNNK54R6S",
        "state": "verified",
        "domain": "foo-corp.com",
        "object": "organization_domain",
        "organization_id": "org_01HV1VNQBQ24JVREYB94RFCNDC",
        "verification_strategy": "manual"
      }
    ],
    "metadata": {
      "tier": "diamond"
    },
    "stripe_customer_id": "cus_R9qWAGMQ6nGE7V",
    "created_at": "2023-11-16T16:32:25.239Z",
    "updated_at": "2023-11-16T17:32:25.239Z"
  },
  "created_at": "2023-11-16T17:32:25.239Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization](https://workos.com/docs/reference/organization)
object.

Triggered when an organization is deleted

## Organization domain events

Events emitted when organization domains are created, updated, deleted, or their verification status changes.

:::code-group{title="Organization domain created event"}

```json language="json"
{
  "event": "organization_domain.created",
  "id": "event_01G69A9MDSW8MM1XW5S0EHA0NA",
  "data": {
    "object": "organization_domain",
    "id": "org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "domain": "foo-corp.com",
    "state": "pending",
    "verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
    "verification_strategy": "dns",
    "verification_prefix": "superapp-domain-verification-z3kjny",
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization
Domain](https://workos.com/docs/reference/domain-verification) object.

Triggered when an organization domain is created.

:::code-group{title="Organization domain updated event"}

```json language="json"
{
  "event": "organization_domain.updated",
  "id": "event_01G69A9MDSW8MM1XW5S0EHA0NA",
  "data": {
    "object": "organization_domain",
    "id": "org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "domain": "foo-corp.com",
    "state": "verified",
    "verification_prefix": "superapp-domain-verification-z3kjny",
    "verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
    "verification_strategy": "dns",
    "created_at": "2022-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization
Domain](https://workos.com/docs/reference/domain-verification) object.

Triggered when an organization domain is updated.

:::code-group{title="Organization domain deleted event"}

```json language="json"
{
  "event": "organization_domain.deleted",
  "id": "event_01G69A9MDSW8MM1XW5S0EHA0NA",
  "data": {
    "object": "organization_domain",
    "id": "org_domain_01EZTR5N6Y9RQKHK2E9F31KZX6",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "domain": "foo-corp.com",
    "state": "verified",
    "verification_prefix": "superapp-domain-verification-z3kjny",
    "verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
    "verification_strategy": "dns",
    "created_at": "2022-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization
Domain](https://workos.com/docs/reference/domain-verification) object.

Triggered when an organization domain is deleted.

:::code-group{title="Organization domain verified event"}

```json language="json"
{
  "event": "organization_domain.verified",
  "id": "event_07FKJ843CVE8F7BXQSPFH0M53A",
  "data": {
    "object": "organization_domain",
    "id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
    "organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T",
    "domain": "foo-corp.com",
    "state": "verified",
    "verification_prefix": "superapp-domain-verification-z3kjny",
    "verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
    "verification_strategy": "dns",
    "created_at": "2022-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization
Domain](https://workos.com/docs/reference/domain-verification) object.

Triggered when an organization domain is verified.

:::code-group{title="Organization domain verification failed event"}

```json language="json"
{
  "event": "organization_domain.verification_failed",
  "id": "event_07FKJ843CVE8F7BXQSPFH0M53A",
  "data": {
    "reason": "domain_verification_period_expired",
    "organization_domain": {
      "object": "organization_domain",
      "id": "org_domain_01HACSKJ57W8M2Q0N2X759C5HS",
      "organization_id": "org_01EHT88Z8J8795GZNQ4ZP1J81T",
      "domain": "foo-corp.com",
      "state": "failed",
      "verification_token": "gBIJgYXZLjW8uHHpz614dkgqm",
      "verification_strategy": "dns"
    }
  },
  "created_at": "2021-06-25T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` contains a `reason` and an `organization_domain` which
corresponds to the [Organization Domain](https://workos.com/docs/reference/domain-verification)
object.

Triggered when an organization domain verification fails.

## Organization membership events

Events emitted when an [AuthKit user](https://workos.com/docs/reference/authkit/user) joins or leaves an organization.

:::code-group{title="Organization membership created event"}

```json language="json"
{
  "event": "organization_membership.created",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "om_01E4ZCR3C56J083X43JQXF3JK5",
    "object": "organization_membership",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
    "status": "pending",
    "role": {
      "slug": "member"
    },
    "roles": [
      {
        "slug": "member"
      }
    ],
    "custom_attributes": {
      "department": "Engineering",
      "job_title": "Software Engineer"
    },
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization
Membership](https://workos.com/docs/reference/authkit/organization-membership) object.

Triggered when an organization membership is created.

:::code-group{title="Organization membership deleted event"}

```json language="json"
{
  "event": "organization_membership.deleted",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M97T",
  "data": {
    "id": "om_01E4ZCR3C56J083X43JQXF3JK5",
    "object": "organization_membership",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
    "status": "active",
    "role": {
      "slug": "member"
    },
    "roles": [
      {
        "slug": "member"
      }
    ],
    "custom_attributes": {
      "department": "Engineering",
      "job_title": "Software Engineer"
    },
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-27T03:14:45.864Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization
Membership](https://workos.com/docs/reference/authkit/organization-membership) object.

Triggered when an organization membership is deleted.

:::code-group{title="Organization membership updated event"}

```json language="json"
{
  "event": "organization_membership.updated",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M30K",
  "data": {
    "id": "om_01E4ZCR3C56J083X43JQXF3JK5",
    "object": "organization_membership",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "organization_id": "org_01E4ZCR3C56J083X43JQXF3JK5",
    "status": "active",
    "role": {
      "slug": "member"
    },
    "roles": [
      {
        "slug": "member"
      }
    ],
    "custom_attributes": {
      "department": "Engineering",
      "job_title": "Software Engineer"
    },
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-18T17:10:15.121Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [Organization
Membership](https://workos.com/docs/reference/authkit/organization-membership) object.

Triggered when an organization membership is updated.

## Custom role events

Events emitted when [custom roles](https://workos.com/docs/reference/roles/custom-role) are created, updated, or deleted.

:::code-group{title="Custom role created event"}

```json language="json"
{
  "event": "organization_role.created",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWD",
  "data": {
    "object": "organization_role",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "slug": "admin",
    "name": "Admin",
    "description": "Administrator role with full access",
    "resource_type_slug": "organization",
    "permissions": ["users:read", "users:write", "settings:manage"],
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the custom role object.

Triggered when a custom role is created.

:::code-group{title="Custom role deleted event"}

```json language="json"
{
  "event": "organization_role.deleted",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWE",
  "data": {
    "object": "organization_role",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "slug": "admin",
    "name": "Admin",
    "description": "Administrator role with full access",
    "resource_type_slug": "organization",
    "permissions": ["users:read", "users:write", "settings:manage"],
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the custom role object.

Triggered when a custom role is deleted.

:::code-group{title="Custom role updated event"}

```json language="json"
{
  "event": "organization_role.updated",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWF",
  "data": {
    "object": "organization_role",
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "slug": "admin",
    "name": "Admin",
    "description": "Administrator role with full access",
    "resource_type_slug": "organization",
    "permissions": ["users:read", "users:write", "settings:manage"],
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the custom role object.

Triggered when a custom role is updated.

## Password reset events

Events emitted when a user requests to reset their password.

:::code-group{title="Password reset created event"}

```json language="json"
{
  "event": "password_reset.created",
  "id": "event_01HYGAT2P3A8XJ4E5AR88J02ZV",
  "data": {
    "object": "password_reset",
    "id": "password_reset_01HYGATMCSBX77HQHP29XT5WV6",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "expires_at": "2023-11-16T21:32:25.235Z",
    "created_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the [Organization
Membership](https://workos.com/docs/reference/authkit/password-reset) object with the `token`
omitted.

Triggered when a user requests to reset their password.

:::code-group{title="Password reset succeeded event"}

```json language="json"
{
  "event": "password_reset.succeeded",
  "id": "event_01HYGAT2P3A8XJ4E5AR88J02ZV",
  "data": {
    "object": "password_reset",
    "id": "password_reset_01HYGATMCSBX77HQHP29XT5WV6",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "expires_at": "2023-11-16T21:32:25.235Z",
    "created_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the [Password
Reset](https://workos.com/docs/reference/authkit/password-reset) object with the `token` omitted.

Triggered when a user successfully resets their password.

## Permission events

Events emitted when [permissions](https://workos.com/docs/reference/roles/permission) are created, updated, or deleted.

:::code-group{title="Permission created event"}

```json language="json"
{
  "event": "permission.created",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWG",
  "data": {
    "object": "permission",
    "id": "01HWDP91J37GZW2FT9GCEX8YWV",
    "slug": "users:read",
    "name": "Read Users",
    "description": "Allows reading user data",
    "system": false,
    "resource_type_slug": "organization",
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the permission object.

<Event.Description>Triggered when a permission is created.</Event.Description>

:::code-group{title="Permission deleted event"}

```json language="json"
{
  "event": "permission.deleted",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWH",
  "data": {
    "object": "permission",
    "id": "01HWDP91J37GZW2FT9GCEX8YWV",
    "slug": "users:read",
    "name": "Read Users",
    "description": "Allows reading user data",
    "system": false,
    "resource_type_slug": "organization",
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the permission object.

<Event.Description>Triggered when a permission is deleted.</Event.Description>

:::code-group{title="Permission updated event"}

```json language="json"
{
  "event": "permission.updated",
  "id": "event_01HWDP814K1EN7VS6K3BD49GWI",
  "data": {
    "object": "permission",
    "id": "01HWDP91J37GZW2FT9GCEX8YWV",
    "slug": "users:read",
    "name": "Read Users",
    "description": "Allows reading user data",
    "system": false,
    "resource_type_slug": "organization",
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "created_at": "2023-11-27T19:07:33.155Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the permission object.

<Event.Description>Triggered when a permission is updated.</Event.Description>

## Pipes events

Events emitted when a [Pipes](https://workos.com/docs/pipes) connected account is connected, disconnected, requires reauthorization, or fails to connect.

Pipes emits two families of these events. The `pipes.connected_account.*` family covers only each owner's compatibility connection. The `pipes.account_connection.*` family covers every connection, including additional connections for the same owner and provider, and is the one to subscribe to if you support them. An endpoint subscribed to both receives two events for each change to a compatibility connection.

:::code-group{title="Pipes connected account connected event"}

```json language="json"
{
  "event": "pipes.connected_account.connected",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD67W",
  "data": {
    "object": "connected_account",
    "id": "data_installation_01HX1ZWK1Z5H5Q7Y7X5EJ09MQ1",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "connection_role": "compatibility",
    "account_identifier": null,
    "account_display_name": "Work GitHub",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "scopes": [
      "repo",
      "user:email"
    ],
    "auth_method": "oauth",
    "api_key_last_4": null,
    "state": "connected",
    "established_by_user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "state_reason": null,
    "created_at": "2024-05-01T12:00:00.000Z",
    "updated_at": "2024-05-01T12:00:00.000Z"
  },
  "created_at": "2024-05-01T12:00:00.000Z"
}
```

:::

Triggered when a connected account completes authorization.

:::code-group{title="Pipes connected account disconnected event"}

```json language="json"
{
  "event": "pipes.connected_account.disconnected",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD67X",
  "data": {
    "object": "connected_account",
    "id": "data_installation_01HX1ZWK1Z5H5Q7Y7X5EJ09MQ1",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "connection_role": "compatibility",
    "account_identifier": null,
    "account_display_name": "Work GitHub",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "scopes": [
      "repo",
      "user:email"
    ],
    "auth_method": "oauth",
    "api_key_last_4": null,
    "state": "connected",
    "established_by_user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "state_reason": null,
    "created_at": "2024-05-01T12:00:00.000Z",
    "updated_at": "2024-05-08T09:30:00.000Z"
  },
  "created_at": "2024-05-08T09:30:00.000Z"
}
```

:::

Triggered when a connected account is disconnected.

:::code-group{title="Pipes connected account reauthorization needed event"}

```json language="json"
{
  "event": "pipes.connected_account.reauthorization_needed",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD67Y",
  "data": {
    "object": "connected_account",
    "id": "data_installation_01HX1ZWK1Z5H5Q7Y7X5EJ09MQ1",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "connection_role": "compatibility",
    "account_identifier": null,
    "account_display_name": "Work GitHub",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "scopes": [
      "repo",
      "user:email"
    ],
    "auth_method": "oauth",
    "api_key_last_4": null,
    "state": "needs_reauthorization",
    "established_by_user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "state_reason": null,
    "created_at": "2024-05-01T12:00:00.000Z",
    "updated_at": "2024-05-08T09:30:00.000Z"
  },
  "created_at": "2024-05-08T09:30:00.000Z"
}
```

:::

Triggered when a connected account needs to be reauthorized.

:::code-group{title="Pipes connected account connection failed event"}

```json language="json"
{
  "event": "pipes.connected_account.connection_failed",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD67Z",
  "data": {
    "object": "connection_failed",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "account_identifier": null,
    "error_code": "provider_error",
    "error_reason": "The provider denied the authorization request.",
    "provider_error": "access_denied",
    "provider_error_description": "The user denied the authorization request.",
    "created_at": "2024-05-01T12:00:00.000Z"
  },
  "created_at": "2024-05-01T12:00:00.000Z"
}
```

:::

Triggered when creating or reauthorizing a compatibility connection fails. The payload describes the attempt, not a connected account.

:::code-group{title="Pipes account connection connected event"}

```json language="json"
{
  "event": "pipes.account_connection.connected",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD680",
  "data": {
    "object": "connected_account",
    "id": "data_installation_01HX1ZWK1Z5H5Q7Y7X5EJ09MQ1",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "connection_role": "standard",
    "account_identifier": null,
    "account_display_name": "Work GitHub",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "scopes": [
      "repo",
      "user:email"
    ],
    "auth_method": "oauth",
    "api_key_last_4": null,
    "state": "connected",
    "established_by_user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "state_reason": null,
    "created_at": "2024-05-01T12:00:00.000Z",
    "updated_at": "2024-05-01T12:00:00.000Z"
  },
  "created_at": "2024-05-01T12:00:00.000Z"
}
```

:::

Triggered when any connection completes authorization.

:::code-group{title="Pipes account connection disconnected event"}

```json language="json"
{
  "event": "pipes.account_connection.disconnected",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD681",
  "data": {
    "object": "connected_account",
    "id": "data_installation_01HX1ZWK1Z5H5Q7Y7X5EJ09MQ1",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "connection_role": "standard",
    "account_identifier": null,
    "account_display_name": "Work GitHub",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "scopes": [
      "repo",
      "user:email"
    ],
    "auth_method": "oauth",
    "api_key_last_4": null,
    "state": "connected",
    "established_by_user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "state_reason": null,
    "created_at": "2024-05-01T12:00:00.000Z",
    "updated_at": "2024-05-08T09:30:00.000Z"
  },
  "created_at": "2024-05-08T09:30:00.000Z"
}
```

:::

Triggered when any connection is disconnected.

:::code-group{title="Pipes account connection reauthorization needed event"}

```json language="json"
{
  "event": "pipes.account_connection.reauthorization_needed",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD682",
  "data": {
    "object": "connected_account",
    "id": "data_installation_01HX1ZWK1Z5H5Q7Y7X5EJ09MQ1",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "connection_role": "standard",
    "account_identifier": null,
    "account_display_name": "Work GitHub",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "scopes": [
      "repo",
      "user:email"
    ],
    "auth_method": "oauth",
    "api_key_last_4": null,
    "state": "needs_reauthorization",
    "established_by_user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "state_reason": null,
    "created_at": "2024-05-01T12:00:00.000Z",
    "updated_at": "2024-05-08T09:30:00.000Z"
  },
  "created_at": "2024-05-08T09:30:00.000Z"
}
```

:::

Triggered when any connection needs to be reauthorized.

:::code-group{title="Pipes account connection failed event"}

```json language="json"
{
  "event": "pipes.account_connection.connection_failed",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD683",
  "data": {
    "object": "connection_failed",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "account_identifier": null,
    "error_code": "provider_error",
    "error_reason": "The provider denied the authorization request.",
    "provider_error": "access_denied",
    "provider_error_description": "The user denied the authorization request.",
    "created_at": "2024-05-01T12:00:00.000Z"
  },
  "created_at": "2024-05-01T12:00:00.000Z"
}
```

:::

Triggered when creating a connection without an add intent, or reauthorizing any connection, fails. The payload describes the attempt, not a connected account.

:::code-group{title="Pipes account connection add failed event"}

```json language="json"
{
  "event": "pipes.account_connection.add_failed",
  "id": "event_01HX1ZX6Q0BP4Z1RBD8N9AD684",
  "data": {
    "object": "connection_failed",
    "data_integration_id": "data_integration_01HX1ZVGJTYGB4YPB4JZM0WS8E",
    "provider_slug": "github",
    "user_id": "user_01HX1ZVZRQQJ4N90R7GG4A1TRG",
    "organization_id": null,
    "account_identifier": null,
    "error_code": "connected_account_limit_reached",
    "error_reason": "The connected account limit for this provider and owner has been reached. Disconnect an account before starting a new connection.",
    "provider_error": null,
    "provider_error_description": null,
    "created_at": "2024-05-01T12:00:00.000Z"
  },
  "created_at": "2024-05-01T12:00:00.000Z"
}
```

:::

Triggered when an add that sent `connection_intent: "add"` fails. No connection exists yet, so the payload carries no connected account id.

## Radar events

Events emitted when [Radar](https://workos.com/docs/authkit/radar) creates a challenge during authentication.

:::code-group{title="Radar challenge created event"}

```json language="json"
{
  "event": "radar.challenge_created",
  "id": "event_01HWWSTZVFADJG9M9EJMKXB043",
  "data": {
    "type": "email",
    "radar_challenge_id": "radar_challenge_01HWZBQZY2M3AMQW166Q22K88F",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "user@example.com"
  },
  "created_at": "2023-11-16T16:32:25.239Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when Radar creates a challenge during authentication. The `type`
field indicates the challenge type (e.g. `email`). Use the `radar_challenge_id`
to fetch the full challenge details via `GET /user_management/radar_challenges/:id`.

## Role events

Events emitted when [environment roles](https://workos.com/docs/reference/roles/role) are created, updated, or deleted.

:::code-group{title="Role created event"}

```json language="json"
{
  "event": "role.created",
  "id": "event_02F4KLW3C56P083X43JQXF4FO9",
  "data": {
    "object": "role",
    "slug": "admin",
    "permissions": ["posts:view"],
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T21:32:25.245Z",
  "context": {}
}
```

:::

<Event.Description>Triggered when a role is created.</Event.Description>

:::code-group{title="Role deleted event"}

```json language="json"
{
  "event": "role.deleted",
  "id": "event_01E4YCD3C56P083X43JQXF4JK5",
  "data": {
    "object": "role",
    "slug": "developer",
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-18T10:12:18.121Z"
  },
  "created_at": "2023-11-21T18:14:01.399Z",
  "context": {}
}
```

:::

<Event.Description>Triggered when a role is deleted.</Event.Description>

:::code-group{title="Role updated event"}

```json language="json"
{
  "event": "role.updated",
  "id": "event_01J21G0ED0N5Q5KZT9Z127Q2MZ",
  "data": {
    "object": "role",
    "slug": "admin",
    "permissions": ["posts:create", "posts:delete"],
    "created_at": "2023-11-16T21:32:25.235Z",
    "updated_at": "2023-11-16T21:32:25.235Z"
  },
  "created_at": "2023-11-16T21:32:25.245Z",
  "context": {}
}
```

:::

Triggered when a role's permissions are updated.

## Session events

Events emitted when AuthKit sessions are created.

:::code-group{title="Session created event"}

```json language="json"
{
  "event": "session.created",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "object": "session",
    "id": "session_01HSCBECW0D7AY8CA45AYKA64G",
    "user_id": "user_01HQGXWZW8BSHRG3HVK2QF7XBX",
    "organization_id": "org_01HQHCBRRAVQ7N3PX81VKAYXSX",
    "impersonator": {
      "email": "admin@example.com",
      "reason": "Helping a customer fix an issue with their account."
    },
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "created_at": "2024-03-19T21:56:25.080Z",
    "updated_at": "2024-03-19T21:56:25.080Z"
  },
  "created_at": "2024-03-19T21:56:25.080Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when a session is created. Sessions started using
[impersonation](https://workos.com/docs/authkit/impersonation) will include an additional
`impersonator` field with data about the impersonator.

:::code-group{title="Session revoked event"}

```json language="json"
{
  "event": "session.revoked",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53B",
  "data": {
    "object": "session",
    "id": "session_01HSCBECW0D7AY8CA45AYKA64G",
    "user_id": "user_01HQGXWZW8BSHRG3HVK2QF7XBX",
    "organization_id": "org_01HQHCBRRAVQ7N3PX81VKAYXSX",
    "impersonator": {
      "email": "admin@example.com",
      "reason": "Helping a customer fix an issue with their account."
    },
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "created_at": "2024-03-19T21:56:25.080Z",
    "updated_at": "2024-03-19T21:56:25.080Z"
  },
  "created_at": "2024-03-19T21:56:25.080Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Triggered when an issued session is revoked for a user.

## User events

Events emitted when [AuthKit users](https://workos.com/docs/reference/authkit/user) are created, updated, or deleted.

:::code-group{title="User created event"}

```json language="json"
{
  "event": "user.created",
  "id": "event_02F4KLW3C56P083X43JQXF4FO9",
  "data": {
    "object": "user",
    "id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "first_name": "Todd",
    "last_name": "Rundgren",
    "name": "Todd Rundgren",
    "email_verified": false,
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "last_sign_in_at": null,
    "locale": "en",
    "external_id": null,
    "metadata": {},
    "created_at": "2023-11-18T09:18:13.120Z",
    "updated_at": "2023-11-18T09:18:13.120Z"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {
    "client_id": "client_123456789"
  }
}
```

:::

Payload `data` corresponds to the [User](https://workos.com/docs/reference/authkit/user) object.

<Event.Description>Triggered when a user is created.</Event.Description>

:::code-group{title="User deleted event"}

```json language="json"
{
  "event": "user.deleted",
  "id": "event_123456abcd",
  "data": {
    "object": "user",
    "id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "first_name": "Todd",
    "last_name": "Rundgren",
    "name": "Todd Rundgren",
    "email_verified": true,
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "last_sign_in_at": null,
    "locale": "en",
    "external_id": null,
    "created_at": "2023-11-16T21:26:25.427Z",
    "updated_at": "2023-11-17T04:00:03.937Z"
  },
  "created_at": "2023-11-18T04:18:13.126Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [User](https://workos.com/docs/reference/authkit/user) object.

<Event.Description>Triggered when a user is deleted.</Event.Description>

:::code-group{title="User updated event"}

```json language="json"
{
  "event": "user.updated",
  "id": "event_02F4KLW3C56P083X43JQXF4FO9",
  "data": {
    "object": "user",
    "id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "first_name": "Todd",
    "last_name": "Rundgren",
    "name": "Todd Rundgren",
    "email_verified": true,
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "last_sign_in_at": null,
    "locale": "en",
    "external_id": null,
    "metadata": {},
    "created_at": "2023-11-18T09:18:13.120Z",
    "updated_at": "2023-11-19T11:05:10.539Z"
  },
  "created_at": "2023-11-19T11:05:10.550Z",
  "context": {}
}
```

:::

Payload `data` corresponds to the [User](https://workos.com/docs/reference/authkit/user) object.

<Event.Description>Triggered when a user is updated.</Event.Description>

## Vault events

Events emitted when [Vault](https://workos.com/docs/vault) data, keys, or metadata are accessed or modified.

:::code-group{title="Vault BYOK key deleted event"}

```json language="json"
{
  "event": "vault.byok_key.deleted",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT8Y",
  "data": {
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "key_provider": "AWS_KMS"
  },
  "created_at": "2024-07-15T10:30:00.000Z",
  "context": {}
}
```

:::

Triggered when a bring-your-own-key (BYOK) configuration is deleted from an
organization.

:::code-group{title="Vault BYOK key verification completed event"}

```json language="json"
{
  "event": "vault.byok_key.verification_completed",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT8Y",
  "data": {
    "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "key_provider": "AWS_KMS",
    "verified": true
  },
  "created_at": "2024-07-15T10:30:00.000Z",
  "context": {}
}
```

:::

Triggered when bring-your-own-key (BYOK) verification completes for an
organization.

:::code-group{title="Vault data created event"}

```json language="json"
{
  "event": "vault.data.created",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT8Y",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "kv_name": "user-ssn",
    "key_id": "vault_key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "key_context": {
      "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E"
    }
  },
  "created_at": "2024-07-15T10:30:00.000Z",
  "context": {}
}
```

:::

Triggered when a new encrypted object is stored in Vault.

:::code-group{title="Vault data deleted event"}

```json language="json"
{
  "event": "vault.data.deleted",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9A",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "kv_name": "user-ssn"
  },
  "created_at": "2024-07-15T10:35:00.000Z",
  "context": {}
}
```

:::

Triggered when an encrypted object is deleted from Vault.

:::code-group{title="Vault data read event"}

```json language="json"
{
  "event": "vault.data.read",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9B",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "kv_name": "user-ssn",
    "key_id": "vault_key_01JMD5H7X3KQXR9VBN2GW4FT8Y"
  },
  "created_at": "2024-07-15T10:32:00.000Z",
  "context": {}
}
```

:::

Triggered when an encrypted object is read from Vault.

:::code-group{title="Vault data updated event"}

```json language="json"
{
  "event": "vault.data.updated",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9C",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "kv_name": "user-ssn",
    "key_id": "vault_key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "key_context": {
      "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E"
    }
  },
  "created_at": "2024-07-15T10:31:00.000Z",
  "context": {}
}
```

:::

Triggered when an existing encrypted object is updated in Vault.

:::code-group{title="Vault DEK decrypted event"}

```json language="json"
{
  "event": "vault.dek.decrypted",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9D",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "key_id": "vault_key_01JMD5H7X3KQXR9VBN2GW4FT8Y"
  },
  "created_at": "2024-07-15T10:40:00.000Z",
  "context": {}
}
```

:::

Triggered when a data encryption key (DEK) is decrypted.

:::code-group{title="Vault DEK read event"}

```json language="json"
{
  "event": "vault.dek.read",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9E",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "key_ids": [
      "vault_key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
      "vault_key_01JMD5H7X3KQXR9VBN2GW4FT9F"
    ],
    "key_context": {
      "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E"
    }
  },
  "created_at": "2024-07-15T10:38:00.000Z",
  "context": {}
}
```

:::

Triggered when one or more data encryption keys (DEKs) are read.

:::code-group{title="Vault DEK rekeyed event"}

```json language="json"
{
  "event": "vault.dek.rekeyed",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9E",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "key_ids": [
      "vault_key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
      "vault_key_01JMD5H7X3KQXR9VBN2GW4FT9F"
    ],
    "key_context": {
      "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E"
    }
  },
  "created_at": "2024-07-15T10:38:00.000Z",
  "context": {}
}
```

:::

Triggered when a data encryption key (DEK) is re-encrypted under a new key
context.

:::code-group{title="Vault KEK created event"}

```json language="json"
{
  "event": "vault.kek.created",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9G",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "key_name": "production-kek",
    "key_id": "vault_key_01JMD5H7X3KQXR9VBN2GW4FT8Y"
  },
  "created_at": "2024-07-15T10:36:00.000Z",
  "context": {}
}
```

:::

Triggered when a new key encryption key (KEK) is created.

:::code-group{title="Vault metadata read event"}

```json language="json"
{
  "event": "vault.metadata.read",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9H",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key",
    "kv_name": "user-ssn"
  },
  "created_at": "2024-07-15T10:34:00.000Z",
  "context": {}
}
```

:::

Triggered when metadata for a Vault store is read.

:::code-group{title="Vault names listed event"}

```json language="json"
{
  "event": "vault.names.listed",
  "id": "event_01JMD5H7X3KQXR9VBN2GW4FT9J",
  "data": {
    "actor_id": "key_01JMD5H7X3KQXR9VBN2GW4FT8Y",
    "actor_source": "api",
    "actor_name": "My API Key"
  },
  "created_at": "2024-07-15T10:33:00.000Z",
  "context": {}
}
```

:::

Triggered when the list of Vault store names is retrieved.
