@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/deprecations/raw-attributes.mdx

@@ -0,0 +1,136 @@
+---
+title: Migrate from raw_attributes
+description: >-
+  How to migrate from raw_attributes and legacy standard attributes to custom
+  attributes.
+originalPath: .tmp-workos-clone/packages/docs/content/deprecations/raw-attributes.mdx
+---
+
+## Overview
+
+On **April 15, 2026**, two changes take effect across Directory Sync and SSO:
+
+1. **`raw_attributes` will stop returning data.** The field will return an empty object everywhere your integration consumes it:
+
+   - **API responses** — when you fetch [Directory Users](/reference/directory-sync/directory-user), [Directory Groups](/reference/directory-sync/directory-group), or [SSO Profiles](/reference/sso/profile)
+   - **Webhooks and Events API** — on all Directory Sync user events (`dsync.user.created`, `dsync.user.updated`, `dsync.user.deleted`) and group events (`dsync.group.created`, `dsync.group.deleted`, `dsync.group.user_added`, `dsync.group.user_removed`)
+
+2. **Top-level `job_title`, `username`, and `emails` will be removed** from [Directory User](/reference/directory-sync/directory-user) objects. These fields will return `null` (or `[]` for `emails`).
+
+> **Your customers do not need to make any changes.** You do not need to coordinate with your customers' IT admins or ask them to remap anything. See the migration paths below for what you need to do.
+
+---
+
+## Migrating from `raw_attributes`
+
+If your code reads from `raw_attributes` on [Directory Users](/reference/directory-sync/directory-user) or [SSO Profiles](/reference/sso/profile), [contact us](mailto:support@workos.com) and we will automatically set up the equivalent custom attribute mappings across all of your existing connections. You then update your code to read from `custom_attributes` instead.
+
+You can also configure custom attribute mappings yourself from the [IdP Attributes page](https://dashboard.workos.com/environment/identity-provider-attributes) in the Dashboard. See [Custom Attributes for Directory Sync](/directory-sync/attributes/custom-attributes/custom-attributes) or [Custom Attributes for SSO](/sso/attributes/custom-attributes/custom-attributes) for details.
+
+```javascript title="Before"
+// Directory Sync - nested fields
+const licenseTier =
+  user.raw_attributes[
+    'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User'
+  ]?.license_tier;
+const employeeId = user.raw_attributes.customSchemas?.Company?.employeeId;
+
+// SSO
+const department = profile.raw_attributes.department;
+```
+
+```javascript title="After"
+// Directory Sync - custom attributes
+const licenseTier = user.custom_attributes.license_tier;
+const employeeId = user.custom_attributes.employee_id;
+
+// SSO
+const department = profile.custom_attributes.department_name;
+```
+
+> **Using AuthKit?** If you access `raw_attributes` via the SSO Profile or Directory User API, the migration above applies to you. Additionally, you can now access IdP attributes directly in AuthKit JWTs and the Organization Membership API - no standalone API call needed. See [Custom Attributes in AuthKit](/authkit/jwt-templates/custom-attributes).
+
+---
+
+## Migrating from legacy standard attributes
+
+If your code reads `job_title`, `username`, or `emails` from the top level of Directory User objects, you can migrate without contacting us:
+
+1. Update your code to read from `custom_attributes` with a fallback to the top-level field, then deploy.
+2. Enable the equivalent [predefined attribute](https://dashboard.workos.com/environment/identity-provider-attributes) in the WorkOS Dashboard.
+
+This order ensures no data is missed during the transition - your code handles both locations until the predefined attribute is active.
+
+```javascript title="Before"
+const jobTitle = user.job_title;
+const emails = user.emails;
+const username = user.username;
+```
+
+```javascript title="Step 1: Deploy with fallback"
+const jobTitle = user.custom_attributes?.job_title ?? user.job_title;
+const emails = user.custom_attributes?.emails ?? user.emails;
+const username = user.custom_attributes?.username ?? user.username;
+```
+
+```javascript title="Step 2: After enabling predefined attributes, clean up"
+const jobTitle = user.custom_attributes.job_title;
+const emails = user.custom_attributes.emails;
+const username = user.custom_attributes.username;
+```
+
+> If you use `emails` only to get the user's primary email address, you can use the `email` standard attribute instead, which remains on the top-level Directory User object.
+
+---
+
+## Example payload
+
+```json title="Before"
+{
+  "id": "directory_user_xxxxx",
+  "idp_id": "xyz",
+  "email": "marcelina@example.com",
+  "job_title": "Software Engineer",
+  "username": "marcelinadavis",
+  "emails": [
+    { "type": "work", "value": "marcelina@example.com", "primary": true }
+  ],
+  "custom_attributes": {},
+  "raw_attributes": {
+    "name": { "givenName": "Marcelina", "familyName": "Davis" },
+    "userName": "marcelinadavis",
+    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
+      "department": "Engineering",
+      "costCenter": "R&D"
+    }
+  }
+}
+```
+
+```json title="After"
+{
+  "id": "directory_user_xxxxx",
+  "idp_id": "xyz",
+  "email": "marcelina@example.com",
+  "custom_attributes": {
+    "job_title": "Software Engineer",
+    "username": "marcelinadavis",
+    "emails": [
+      { "type": "work", "value": "marcelina@example.com", "primary": true }
+    ],
+    "department_name": "Engineering",
+    "cost_center_name": "R&D"
+  }
+}
+```
+
+---
+
+## Learn more
+
+- [Custom Attributes for Directory Sync](/directory-sync/attributes/custom-attributes/custom-attributes)
+- [Custom Attributes for SSO](/sso/attributes/custom-attributes/custom-attributes)
+- [Predefined Attributes](/directory-sync/attributes/custom-attributes/predefined-attributes)
+- [Custom Attributes in AuthKit](/authkit/jwt-templates/custom-attributes) - [Changelog](https://workos.com/changelog/custom-attributes-in-authkit)
+- [SAML Custom Attributes](https://workos.com/changelog/saml-custom-attributes)
+- [OIDC Attributes](https://workos.com/changelog/oidc-attributes)

package/.docs/organized/docs/directory-sync/attributes.mdx

@@ -33,6 +33,7 @@ WorkOS can automatically find and normalize most common attributes from director
           "primary": true
         }
       ],
+      "employee_number": "E-12345",
       "employee_type": "Full Time",
       "employment_start_date": "2021-06-27T12:00:00.000Z",
       "department_name": "Engineering",
@@ -40,6 +41,7 @@ WorkOS can automatically find and normalize most common attributes from director
       "division_name": "Analytics",
       "cost_center_name": "IT",
       "job_title": "Software Engineer",
+      "organization": "Acme Corp",
       "addresses": [
         {
           "type": "work",
@@ -64,27 +66,6 @@ WorkOS can automatically find and normalize most common attributes from director
       ],
       "username": "jane@example.com",
       "my_new_key": "<custom-mapped value>"
-    },
-    "raw_attributes": {
-      "name": {
-        "givenName": "Jane",
-        "familyName": "Doe"
-      },
-      "active": true,
-      "emails": [
-        {
-          "type": "work",
-          "value": "jane@example.com",
-          "primary": true
-        }
-      ],
-      "groups": [],
-      "locale": "en_US",
-      "schemas": ["urn:directory:schemas:core:1.0"],
-      "password": "redacted",
-      "userName": "jane@example.com",
-      "externalId": "821991",
-      "displayName": "Jane Doe"
     }
   }
   ```
@@ -120,7 +101,11 @@ Every Directory User comes with the following standard attributes. These are the
 
 ## Custom attributes
 
-For more detailed user information, you can opt-in to additional predefined attributes and define your own custom attributes. These attributes will appear in the `custom_attributes` field on [Directory User](/reference/directory-sync/directory-user) objects and can be configured in the [WorkOS Dashboard](https://dashboard.workos.com/).
+For more detailed user information, you can opt-in to additional predefined attributes and define your own custom attributes. These attributes will appear in the custom attributes field on [Directory User](/reference/directory-sync/directory-user) objects and can be configured in the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+> Custom attributes are configured at the environment level. To configure attributes for a specific organization, please [contact our support team](mailto:support@workos.com).
+
+> When using AuthKit with directory provisioning, Directory User custom attributes are also available on the organization membership's `custom_attributes` field. See [JWT Templates](/authkit/jwt-templates) for how to include these in your access tokens.
 
 ### Predefined attributes
 
@@ -133,10 +118,12 @@ When enabled, the values will be mapped without additional setup. Not every dire
 | `department_name`       | The user’s department name                                                                                                      |
 | `division_name`         | The user’s division name                                                                                                        |
 | `emails`                | The user’s list of email objects (`type`, `value`, `primary`)                                                                   |
+| `employee_number`       | The user's employee number assigned by the organization                                                                         |
 | `employee_type`         | The user’s employment type                                                                                                      |
 | `employment_start_date` | The user’s start date                                                                                                           |
 | `job_title`             | The user’s job title                                                                                                            |
 | `manager_email`         | The email address for the user’s manager                                                                                        |
+| `organization`          | The name of the user’s organization                                                                                             |
 | `username`              | The user’s username                                                                                                             |
 
 #### Enable or disable a predefined attribute
@@ -171,26 +158,45 @@ When a custom attribute is deleted, the attribute will be deleted from all [Dire
 
 #### Nested attributes
 
-Nested attributes are not currently supported. These admin-defined attributes must be defined as top-level flat keys.
+Custom attributes support nested attribute mapping. Different directory providers structure their data differently, and nested attribute support allows you or your customer to map values regardless of where they appear in the directory structure.
+
+Nested attributes from the directory can be mapped to custom attributes using the WorkOS [Dashboard](https://dashboard.workos.com/) or [Admin Portal](/admin-portal) by selecting attributes from an interactive schema viewer. The schema viewer displays the structure of user data from their directory, allowing them to browse and select any nested field. This ensures accurate mapping without manual configuration.
+
+##### Example: Different structures across providers
+
+The same logical attribute (like "license") may appear at different nesting levels depending on the provider:
 
-For instance, in the following example `top_level_attribute` can be mapped, but `top_level_with_nested.nested_attribute` cannot be mapped:
+```json language="json" title="Provider A - Nested under URN"
+{
+  "userName": "jdoe@example.com",
+  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
+    "license_tier": "silver"
+  }
+}
+```
 
-```json language="json" title="Attributes Example"
+```json language="json" title="Provider B - Under custom schemas"
 {
-  "top_level_attribute": "value",
-  "top_level_with_nested": {
-    "nested_attribute": "nested_value"
+  "userName": "jdoe@example.com",
+  "customSchemas": {
+    "license_tier": "silver"
   }
 }
 ```
 
-> If you are interested in nested attributes support, please [contact support](mailto:support@workos.com).
+With nested attribute support, you can create a single custom attribute called `license_tier`, and IT admins can map it to the correct location in their specific directory provider's structure using the schema viewer.
 
 ---
 
-## Raw attributes [**Deprecated**]
+## Raw attributes [Deprecated]
+
+The `raw_attributes` field on [Directory User](/reference/directory-sync/directory-user) objects is deprecated and will **stop returning data on April 15, 2026**.
+
+[Custom attributes](/directory-sync/attributes/custom-attributes/custom-attributes) and [nested attribute mapping](/directory-sync/attributes/custom-attributes/custom-attributes) are the recommended replacements. These features provide a consistent, structured API while giving IT admins the flexibility to map any field from their directory provider.
 
-These are unfiltered and unstructured attributes that are unique to each directory provider. These attributes are included as fields in the `raw_attributes` object that is included in the [Directory User](/reference/directory-sync/directory-user). The `raw_attributes` property will be phased out by July 22, 2025. [IdP role assignment](/directory-sync/identity-provider-role-assignment) or [custom attributes](/directory-sync/attributes/custom-attributes) should be used instead.
+Contact support [via email](mailto:support@workos.com) or Slack if you need help with the migration. We also have tooling to automate the WorkOS-side configuration on your behalf.
+
+For a full migration walkthrough covering Directory Sync, SSO, and AuthKit, see the [migration guide](/deprecations/raw-attributes).
 
 ---
 
@@ -207,3 +213,16 @@ We do not currently support this functionality, as you have to define any custom
 ### What happens if an attribute cannot be mapped from the IdP?
 
 Attributes that cannot be mapped for a particular [Directory User](/reference/directory-sync/directory-user) will result in a `null` value for the attribute. [dsync.user.updated](/events/directory-sync) events are not emitted when an attribute changes from `null` to `undefined` or vice versa.
+
+### How do IT admins map nested attributes?
+
+IT admins can map nested attributes using the schema viewer in the WorkOS [Admin Portal](/admin-portal) when configuring their directory. The schema viewer displays the actual structure of user data from their directory provider, showing how attributes are organized.
+
+To map a nested attribute:
+
+1. IT admins navigate to the attribute mapping step during directory configuration
+2. They view a visual representation of their directory's user data structure
+3. They select any field, regardless of nesting level, from the schema viewer
+4. The mapping is automatically configured for that nested attribute
+
+This approach works consistently across all directory providers, even though each provider may structure their data differently. The schema viewer adapts to show the specific structure of the IT admin's directory provider, ensuring accurate mapping without requiring technical knowledge of the underlying data format.

package/.docs/organized/docs/directory-sync/example-apps.mdx

@@ -1,46 +1,46 @@
 ---
 title: Example Apps
-description: "View sample Directory\_Sync apps for\_each\_SDK."
+description: View sample Directory Sync apps for each SDK.
 originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/example-apps.mdx
 ---
 
-You can view minimal example apps that demonstrate how to use the WorkOS SDKs to power Directory Sync:
+You can view minimal example apps that demonstrate how to use the WorkOS SDKs to power Directory Sync:
 
 <ExampleApps.Root>
   <ExampleApps.Card
     href="https://github.com/workos/node-example-applications/tree/main/node-directory-sync-example"
-    title="Node.js Directory Sync app"
+    title="Node.js Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/typescript-example-applications/tree/main/typescript-directory-sync-example"
-    title="TypeScript Directory Sync app"
+    title="TypeScript Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/ruby-example-applications/tree/main/ruby-directory-sync-example"
-    title="Ruby Directory Sync app"
+    title="Ruby Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/python-flask-example-applications/tree/main/python-flask-directory-sync-example"
-    title="Python Flask Directory Sync app"
+    title="Python Flask Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/python-django-example-applications/tree/main/python-django-directory-sync-example"
-    title="Python Django Directory Sync app"
+    title="Python Django Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/go-example-applications/tree/main/go-directory-sync-example"
-    title="Go Directory Sync app"
+    title="Go Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/java-example-applications/tree/main/java-directory-sync-example"
-    title="Java Directory Sync app"
+    title="Java Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/php-example-applications/tree/main/php-directory-sync-example"
-    title="PHP Directory Sync app"
+    title="PHP Directory Sync app"
   />
   <ExampleApps.Card
     href="https://github.com/workos/dotnet-example-applications/tree/main/dotnet-directory-sync-example"
-    title=".NET Directory Sync app"
+    title=".NET Directory Sync app"
   />
 </ExampleApps.Root>

package/.docs/organized/docs/directory-sync/identity-provider-role-assignment.mdx

@@ -12,27 +12,7 @@ originalPath: >-
 
 A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by a unique, immutable slug and are assigned to Directory Sync [users](/directory-sync/api-overview/directory-user) through their group memberships. These role assignments can be configured on the WorkOS dashboard.
 
-## Configure roles
-
-You can manage roles in the _Roles & Permissions_ section of the [WorkOS Dashboard](https://dashboard.workos.com/).
-
-![Roles section WorkOS Dashboard](https://images.workoscdn.com/images/d96e9c84-651d-4f5d-af3e-98e3d36b7a9f.png?auto=format&fit=clip&q=50)
-
-### Default role
-
-Role configuration occurs at the environment level. Each environment is seeded with a default `member` role, which is automatically assigned to every directory user. This default role cannot be deleted, but any role can be set as the default.
-
-If you need to set default roles or other role configurations at the organization level, refer to the [organization roles](/user-management/roles-and-permissions/organization-roles) documentation.
-
-### Priority order
-
-If a user is provisioned from multiple groups with conflicting roles, the role with the highest priority will be assigned.
-
-### Delete roles
-
-When a role is deleted, all users with that role, will be granted the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all directory users.
-
-> To migrate from one default role to another, set the new default role and delete the old one. All directory users will then be reassigned to the new default role.
+To utilize Identity Provider (IdP) role assignment, you must first [configure roles](/rbac/configuration).
 
 ## Directory group role assignment
 
@@ -61,11 +41,29 @@ From this point on, all new users added to “Engineering" will be given "Develo
 
 ![Screenshot of directory user page](https://images.workoscdn.com/images/18f584f6-d758-4f11-bfc8-e93c16452580.png?auto=format&fit=clip&q=50)
 
+### Multiple roles
+
+When [multiple roles is enabled](/rbac/configuration/configure-roles/multiple-roles) in your environment, directory users can be assigned multiple roles from their identity provider group memberships. If a user belongs to multiple mapped groups, they will receive all corresponding roles.
+
+For example, if a user is a member of both "Engineering" and "Design" groups, and both groups are mapped to roles, the directory user will receive both the "Developer" and "Designer" roles. If a user is not a member of any groups with explicit mappings, they will receive the [default role](/rbac/configuration).
+
+When using [AuthKit with Directory Provisioning](/authkit/directory-provisioning), these multiple roles are automatically applied to the user's [organization membership](/reference/authkit/organization-membership) and reflected in their [session token](/authkit/sessions/integrating-sessions/access-token).
+
+#### Use cases
+
+By default, multiple roles is disabled and users can only have a single role per entity. It's recommended to start with a single-role setup for simplicity, where it's easier to maintain consistent and correct access patterns.
+
+You might want to enable multiple roles when you need:
+
+- **Cross-department collaboration**: e.g., designers who need some engineering permissions.
+- **Additive, disjoint permissions**: independent permission sets that should stack.
+- **Temporary access**: grant time-bound extra capabilities without creating hybrid roles.
+
 ### Role assignment in Admin Portal
 
-Once [roles](/directory-sync/identity-provider-role-assignment/configure-roles) are configured for your application, enable directory group role assignment in [Admin Portal](/admin-portal) to allow IT admins to assign roles to groups during directory setup.
+Once [roles](/rbac/configuration) are configured for your application, enable directory group role assignment in [Admin Portal](/admin-portal) to allow IT admins to assign roles to groups during directory setup.
 
-![Enable directory group role assignment dashboard setting](https://images.workoscdn.com/images/157af155-1cd5-4714-9a4e-f56dd0005e36.png?auto=format&fit=clip&q=50)
+![Enable directory group role assignment dashboard setting](https://images.workoscdn.com/images/fe19e3ac-6370-404e-9590-cdb06b3de127.png?auto=format&fit=clip&q=50)
 
 This is an environment-level setting, but can be configured per organization via the _Roles_ tab under an organization in the WorkOS Dashboard. If your application is integrated with Directory Sync, it is recommended to use directory group role assignment as the environment default.
 
@@ -114,8 +112,7 @@ You can create a custom-mapped attribute role (e.g., `myRole`) in the [WorkOS Da
   "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3PJNY",
   "custom_attributes": {
     "myRole": "admin"
-  },
-  "raw_attributes": {}
+  }
 }
 ```
 
@@ -127,7 +124,7 @@ An example being that `myRole` should be one of `"admin"`, `"viewer"`, or `"edit
 
 ### A user is part of multiple groups
 
-Having a user who belongs to multiple groups is a common scenario. For example, there might be a case where an employee _Jane_ is an _Engineering Manager_ and belongs to an “Engineering”, “Manager”, and “Admin” group. With group-based role assignment, the user will be assigned the role that has the [highest priority defined](/directory-sync/identity-provider-role-assignment/configure-roles/priority-order).
+Having a user who belongs to multiple groups is a common scenario. For example, there might be a case where an employee _Jane_ is an _Engineering Manager_ and belongs to an “Engineering”, “Manager”, and “Admin” group. With group-based role assignment, the user will be assigned the role that has the [highest priority defined](/rbac/configuration/configure-roles/priority-order).
 
 ### Role assignment availability on Directory Sync
 

package/.docs/organized/docs/directory-sync/index.mdx

@@ -1,6 +1,8 @@
 ---
 title: Directory Sync
-description: "Build frictionless onboarding for\_organizations with\_real‑time user\_provisioning and deprovisioning."
+description: >-
+  Build frictionless onboarding for organizations with real‑time user
+  provisioning and deprovisioning.
 showNextPage: true
 originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/index.mdx
 ---
@@ -86,7 +88,7 @@ Directory Sync makes this integration easy by providing APIs your app interfaces
 
 A directory is the source of truth for your customer’s user and group lists.
 
-WorkOS supports dozens of integrations including SCIM. Directory updates are delivered to you via webhooks. Your app stores a mapping between your customer and their directory. This allows you to maintain your app in sync with the directory provider used by your customer.
+WorkOS supports dozens of integrations including SCIM. Directory updates can be delivered to you via webhooks or retrieved using the [Events API](/reference/events). Your app stores a mapping between your customer and their directory. This allows you to maintain your app in sync with the directory provider used by your customer.
 
 You can enable self-service Directory Sync setup for your customers using the [Admin Portal](/admin-portal).
 

package/.docs/organized/docs/directory-sync/quick-start.mdx

@@ -1,6 +1,6 @@
 ---
 title: Quick Start
-description: "Set up a directory, install the SDK, and\_integrate Directory\_Sync."
+description: 'Set up a directory, install the SDK, and integrate Directory Sync.'
 showNextPage: true
 originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/quick-start.mdx
 ---
@@ -121,9 +121,9 @@ Example use case: Build an onboarding experience that allows an admin to select
 
 ## (3) Handle directory events
 
-Actions performed in a WorkOS environment are represented by events. These can occur as a result of user-related actions, manually via the WorkOS dashboard, or via API calls. To keep your app in sync with the latest directory data, follow the corresponding guides:
+Actions performed in a WorkOS environment are represented by events. These can occur as a result of user-related actions, manually via the WorkOS dashboard, or via API calls. To keep your app in sync with the latest directory data, follow the corresponding guides:
 
+- We recommend using our [events API](/events/data-syncing/events-api) to sync data to your application. To learn more about other ways to sync data, see the [data syncing guide](/events/data-syncing).
 - Learn about the different types of events that you can receive. See [event types](/events).
-- Handle the events you need on your side by syncing the data. See the [data syncing guide](/events/data-syncing).
 - Understand how directory events work. See the [understanding events guide](/directory-sync/understanding-events).
 - Optionally, stream events to Datadog. See the [observability guide](/events/observability/datadog).

package/.docs/organized/docs/directory-sync/understanding-events.mdx

@@ -83,7 +83,7 @@ This event occurs when users’ attributes change. These attributes may be [stan
 
 The payload for `dsync.user.updated` event shows changes between directory group snapshots in the `previous_attributes` property.
 
-The changes in the object are shallow differences for root properties, `raw_attributes`, and `custom_attributes`. If the current snapshot has a new attribute that did not exist previously, then the value for the attribute will be indicated as `null`.
+The changes in the object are shallow differences for root properties and `custom_attributes`. If the current snapshot has a new attribute that did not exist previously, then the value for the attribute will be indicated as `null`.
 
 ### `dsync.user.deleted`
 
@@ -135,7 +135,7 @@ This event is sent when an attribute of a directory group has changed.
 
 The payload for `dsync.group.updated` events shows changes between directory group snapshots in the `previous_attributes` property.
 
-The changes in the object are shallow differences for root properties, `raw_attributes`, and `custom_attributes`. If the current snapshot has a new attribute that did not exist previously, then the value for the attribute will be indicated as `null`.
+The changes in the object are shallow differences for root properties and `custom_attributes`. If the current snapshot has a new attribute that did not exist previously, then the value for the attribute will be indicated as `null`.
 
 ### `dsync.group.deleted`
 

package/.docs/organized/docs/domain-verification/api.mdx

@@ -9,15 +9,15 @@ Instead of leveraging the Admin Portal, the Domain Verification API can be used
 
 Integrating with the API goes as follows:
 
-1. Create an Organization Domain for an Organization
-2. Share the token and setup instructions with the Organization owner (IT Admin)
+1. Create an organization domain for an organization
+2. Share the token and setup instructions with the organization owner (IT admin)
 3. Wait for the verification to complete
 
-## Create a new Organization Domain
+## Create a new organization domain
 
-All domains belong to an [Organization](/reference/organization). In order to create and verify a domain, an Organization must first be [created](/reference/organization/create).
+All domains belong to an [organization](/reference/organization). In order to create and verify a domain, an organization must first be [created](/reference/organization/create).
 
-<CodeBlock title="Create an Organization Domain">
+<CodeBlock title="Create an organization domain">
   <CodeBlockTab title="Request" file="create-organization-domain" />
   <CodeBlockTab title="Response" file="create-organization-domain-response" />
 </CodeBlock>
@@ -31,7 +31,7 @@ The `verification_token` returned can then be set as the value of a TXT record t
 
 Fetch an existing domain and it’s current verification status. This endpoint can be polled once verification has been initiated to determine if verification has been successful.
 
-<CodeBlock title="Fetch an Organization Domain">
+<CodeBlock title="Fetch an organization domain">
   <CodeBlockTab title="Request" file="get-organization-domain" />
   <CodeBlockTab title="Response" file="get-organization-domain-response" />
 </CodeBlock>
@@ -45,13 +45,13 @@ Possible `state` values:
 Possible `verification_strategy` values:
 
 - `dns`: domain is verified with the DNS flow
-- `developer`: domain is verified by a person or a system, without running the DNS flow
+- `manual`: domain is verified by a person or a system, without running the DNS flow
 
 ## Initiate verification for existing domain
 
 If a domain has not successfully verified within thirty days and moves to the `failed` state, verification can be restarted manually.
 
-<CodeBlock title="Verify an existing Organization Domain">
+<CodeBlock title="Verify an existing organization domain">
   <CodeBlockTab title="Request" file="verify-existing-organization-domain" />
   <CodeBlockTab
     title="Response"

package/.docs/organized/docs/domain-verification/index.mdx

@@ -9,7 +9,7 @@ originalPath: .tmp-workos-clone/packages/docs/content/domain-verification/index.
 
 Domain Verification allows your customers to claim ownership of a domain. Once they have claimed ownership, features that require a higher level of trust and security can be activated.
 
-WorkOS Domain Verification provides a self-serve flow through the Admin Portal in which IT Admins can prove ownership through the creation of DNS TXT records.
+WorkOS Domain Verification provides a self-serve flow through the Admin Portal in which IT admins can prove ownership through the creation of DNS TXT records.
 
 ## Before getting started
 
@@ -20,7 +20,7 @@ You’ll need a [WorkOS account](https://dashboard.workos.com/).
 [Organization](/reference/organization)
 : Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.
 
-[Organization Domain](/reference/organization-domain)
+[Organization Domain](/reference/domain-verification)
 : Describes a domain associated to an organization, verified or unverified.
 
 [Portal Link](/reference/admin-portal/portal-link)
@@ -64,4 +64,4 @@ The admin will find instruction to add a DNS TXT record with a token generated b
 
 ![A screenshot showing the Admin Portal domain DNS instructions.](https://images.workoscdn.com/images/9ab7e2a4-8b11-4a03-8203-d95d1c1abb07.png?auto=format&fit=clip&q=80)
 
-When we detect and verify the DNS record, we will mark the domain as `verified` and dispatch a [domain verification event](/events) to inform your application.
+When we detect and verify the DNS record, we will mark the domain as `verified` and dispatch a [domain verification event](/events) to inform your application.

package/.docs/organized/docs/email.mdx

@@ -52,7 +52,7 @@ It is also important to ensure that your WorkOS team account and all organizatio
 
 While using the WorkOS email domain option is convenient, you can provide your users a better experience. Using your own email domain means that your users will receive emails from a domain they recognize, one associated with your app. In addition, because you control the email domain, you have more control over the domain reputation and therefore more control over email deliverability.
 
-You can configure your own email domain in the [WorkOS dashboard](https://dashboard.workos.com). You will need to verify ownership of the domain by setting up a CNAME record with your domain provider. Two additional CNAME records are required to automatically configure SPF and DKIM email authentication using [Sendgrid's automated security feature](https://support.sendgrid.com/hc/en-us/articles/21415314709147-Email-Authentication-SendGrid-s-Automated-Security-Explained).
+You can configure your own email domain in the [WorkOS dashboard](https://dashboard.workos.com). You will need to verify ownership of the domain by setting up a CNAME record with your domain provider. Two additional CNAME records are required to automatically configure SPF and DKIM email authentication using [SendGrid's automated security feature](https://support.sendgrid.com/hc/en-us/articles/21415314709147-Email-Authentication-SendGrid-s-Automated-Security-Explained).
 
 ![Configuring your email domain](https://images.workoscdn.com/images/84e47c58-e5e5-47c3-8245-f414a203f284.png?auto=format&fit=clip&q=50)
 
@@ -84,20 +84,64 @@ More details about DMARC can be found at [dmarc.org](https://dmarc.org/overview/
 
 ---
 
-## (C) Send your own email
+## (C) Connect your own email provider to WorkOS
 
-There are a number of reasons why you may want to send email using your own email provider. Perhaps you already send a welcome email to new users and want to include an invitation link instead of sending a second email. Perhaps you want to translate the email text into different languages. Perhaps you already track sent email status with your own email provider and want a unified view into the status of all emails associated with your app. Regardless, when you send your own email, you have complete control over email deliverability.
+By connecting your own email provider to WorkOS, you get control over deliverability, reputation, and compliance, while still offloading the heavy lifting of email handling. This option also allows you to easily utilize an existing email service provider configuration.
 
-For complete instructions on sending your own email, see the section on [custom emails](/user-management/custom-emails) in the user management documentation.
+For complete instructions on configuring a custom email provider, see the [custom email providers section](/authkit/custom-email-providers).
+
+---
+
+## (D) Send your own email
+
+There are a number of reasons why you may want to send email using your own email provider. Perhaps you already send a welcome email to new users and want to include an invitation link instead of sending a second email. Perhaps you already track sent email status with your own email provider and want a unified view into the status of all emails associated with your app. Regardless, when you send your own email, you have complete control over email deliverability.
+
+For complete instructions on sending your own email, see the section on [custom emails](/authkit/custom-emails) in the AuthKit documentation.
 
 When sending your own email, you will want to follow the all of the recommendations in Google's [email sender guidelines](https://support.google.com/a/answer/81126?hl=en). This includes setting up SPF, DKIM and DMARC email authentication.
 
-You will also need to be conscious of your sender reputation. It's based on the quality of emails, their frequency, and user interaction. A good sender reputation can increase the chances of your emails reaching inboxes. Sendgrid provides some [useful tips for improving sender reputation](https://sendgrid.com/en-us/blog/email-reputation-101-ip-reputation-vs-domain-reputation).
+You will also need to be conscious of your sender reputation. It's based on the quality of emails, their frequency, and user interaction. A good sender reputation can increase the chances of your emails reaching inboxes. SendGrid provides some [useful tips for improving sender reputation](https://sendgrid.com/en-us/blog/email-reputation-101-ip-reputation-vs-domain-reputation).
 
 If you author your own email content, you may want to test your emails against various email providers' spam filters. There are a number of spam testing services available such as [Litmus](https://www.litmus.com/email-testing) and [Warmly](https://www.warmy.io/free-tools/email-deliverability-test/).
 
 ---
 
+## (E) Check suppression status
+
+Email providers maintain suppression lists: addresses that previously bounced, were marked as spam, or were flagged as invalid. Once suppressed, WorkOS will not attempt to deliver emails to that address.
+
+### Suppression types
+
+- **Bounce**: The email hard-bounced because the address doesn't exist.
+- **Spam complaint**: The recipient marked the email as spam.
+- **Block**: The email provider blocked delivery.
+- **Invalid**: The email address is malformed.
+
+### Checking and removing suppressions
+
+In the [WorkOS Dashboard](https://dashboard.workos.com/), navigate to the **Users → [User] → Emails** tab. The suppression status is shown for the user's email address. If suppressed, you can click "Re-enable email" to remove the suppression.
+
+Before removing a suppression, confirm:
+
+- The recipient wants to receive emails.
+- The mailbox is not full and can receive mail.
+- The email address is valid and not malformed.
+
+<Callout type="warning">
+  Removing a suppression for an address that continues to bounce will harm your
+  domain's sender reputation.
+</Callout>
+
+Suppression management is available when using the default WorkOS email provider or a [custom email provider](/authkit/custom-email-providers).
+
+<Callout type="info">
+  Resend is not currently supported for suppression management. If you use
+  Resend as your custom email provider, manage suppressions directly in the
+  Resend dashboard.
+</Callout>
+
+---
+
 ## Troubleshooting
 
 Even when following industry best practices, an email may get filtered as spam and not reach a user's inbox. Other times an email might be delayed, for example, when [Enhanced Pre-delivery Message Scanning](https://apps.google.com/supportwidget/articlehome?hl=en&article_url=https%3A%2F%2Fsupport.google.com%2Fa%2Fanswer%2F7380368%3Fhl%3Den&product_context=7380368&product_name=UnuFlow&trigger_context=a) is enabled on a Google workspace or when a similar feature is enabled with other email providers. Email providers do not explain the heuristics used by their spam filters and security mechanisms, and they are often changing, making it especially frustrating to troubleshoot problems.