@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/authkit/roles-and-permissions.mdx

@@ -0,0 +1,208 @@
+---
+title: Roles and Permissions
+description: Manage and assign roles and permissions to users.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/roles-and-permissions.mdx
+---
+
+## Introduction
+
+A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by unique, immutable slugs and are assigned to users through [organization memberships](/authkit/users-organizations/organizations).
+
+Permissions grant users privileged access to resources and actions in your application and are referenced in your code by unique, immutable slugs. A permission can be assigned to any number of roles.
+
+### Standalone roles
+
+Roles alone can be sufficient when your application only requires very coarse-grained access control. This is suitable if users only need to be separated into broad categories and there is minimal overlap between roles. Simple roles can be easier to manage, but are less flexible for complex access control scenarios.
+
+### Utilizing permissions with roles
+
+Permissions allow for more detailed and flexible management of access. They are particularly useful when:
+
+- You anticipate the need to frequently modify access rights or introduce new roles.
+- There is significant overlap in access rights between different roles, but with some variations.
+- You want to minimize code changes when modifying access rights. By abstracting access control checks to permissions, you can add or modify roles and their access rights without changing the application code.
+
+## Configure roles and permissions
+
+Roles and permissions are managed in their own section of the [WorkOS Dashboard](https://dashboard.workos.com/environment/authorization/) or using the [authorization APIs](/reference/roles).
+
+![Roles section WorkOS Dashboard](https://images.workoscdn.com/images/09c8fb23-5748-4236-914e-79849ac03a9a.png?auto=format&fit=clip&q=50)
+
+### Create permissions
+
+When configuring permissions, we recommend:
+
+- Defining a common naming scheme to use across all permissions for your application. Consider separating the resource and action with a delimiter, such as `users:view`. The following delimiters are permitted: `-.:_*`.
+- Keep permission slugs clear and concise. When assigned to roles, these slugs will be included in session cookies in the [session JWT claims](/authkit/sessions/integrating-sessions/access-token), which is limited to a maximum size of 4KB in many modern web browsers.
+
+### Assign permissions to roles
+
+Permissions can be assigned when creating a new role or when editing an existing role.
+
+![Assign permissions to a role](https://images.workoscdn.com/images/f6fd6d9a-a7b0-4df7-908b-b657e669a3dc.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 organization member. 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](/authkit/roles-and-permissions/organization-roles) section.
+
+### Assign roles
+
+By default, organization memberships require exactly one role. Every user with an organization membership is automatically assigned the default role when added to an organization. This role can be edited.
+
+When [multiple roles is enabled](/authkit/roles-and-permissions/multiple-roles), you can assign several roles to an organization membership. The user gets all permissions from each role.
+
+<DirectorySyncDiagram.Roles />
+
+You can retrieve the role information from the user's [organization membership object](/reference/authkit/organization-membership) to determine their access level and capabilities within your application.
+
+Role changes are tracked and logged via the [`organization_membership.updated` event](/events/organization-membership). To view these changes, go to the [events page](https://dashboard.workos.com/environment/events) and filter by `organization_membership.updated`.
+
+### Delete roles
+
+When roles are deleted:
+
+- **Single role mode**: All organization memberships with the deleted role are reassigned to the default role.
+- **Multiple roles mode**: The deleted role is removed from all organization memberships that have it assigned, while other roles on the organization membership remain intact. If the deleted role was the only role assigned to the membership, it will be reassigned the default role.
+
+Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all affected organization memberships.
+
+> To migrate from one default role to another, set the new default role and delete the old one. All users will then be reassigned to the new default role.
+
+### Priority order
+
+If a user is provisioned from multiple sources with conflicting roles, the role with the highest priority will be assigned. This is applicable for a single role architecture utilizing [role assignment](/authkit/roles-and-permissions/role-assignment).
+
+Priority order also determines which role will be assigned to users when migrating from a multiple roles to single role configuration in the environment.
+
+## Multiple roles
+
+When [enabled](/rbac/configuration/configure-roles/multiple-roles), AuthKit supports multiple roles per organization membership. A user receives the **union of permissions** across all assigned roles. For example, a user with the _Designer_ and _Engineer_ roles gets both sets of permissions in their session. This prevents role explosion by avoiding redundant hybrid roles, like "designer-engineer". Each organization membership must have **at least one** role, they will always receive the default role if no other role(s) are set.
+
+### Use cases
+
+By default, multiple roles is disabled and users can only have a single role per entity. 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.
+
+For most apps, start with **single-role relationships** for simplicity and predictability, and adopt multiple roles only when overlapping permission sets become common.
+
+| Mode           | Access calculation                         | Pros                                         | Considerations                                      |
+| -------------- | ------------------------------------------ | -------------------------------------------- | --------------------------------------------------- |
+| Single role    | One role's permissions per membership      | Simple model; predictable audits; small JWTs | May require hybrid roles for cross-functional users |
+| Multiple roles | Union of permissions across assigned roles | Flexible; avoids role sprawl                 | Larger JWTs; more governance                        |
+
+### Manually assign roles to a user
+
+Roles can be assigned manually following the steps below, or via identity provider roles assignment outlined in the next section.
+
+1. From the WorkOS Dashboard, open [Users](https://dashboard.workos.com/environment/users).
+2. Select a user and go to **Organization memberships**
+3. Click **Edit roles** and add all relevant roles
+4. Or assign roles [via the API](/reference/authkit/organization-membership/update)
+
+Each organization membership must have **at least one** role.
+
+## Role assignment
+
+You can map identity provider groups to roles to automatically assign roles to users. AuthKit supports two methods for role assignment:
+
+### SCIM (Directory Sync)
+
+Roles can be assigned via SCIM through [directory group role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment). Admins can map group memberships to roles in the Admin Portal during SCIM or Google Workspace directory setup. These mappings are used to assign roles to organization memberships via [Directory Provisioning](/authkit/directory-provisioning).
+
+### SSO
+
+Roles can also be assigned via [SSO group role assignment](/sso/identity-provider-role-assignment/sso-group-role-assignment). Groups returned in the SSO profile can be mapped to roles in the WorkOS Dashboard. If an AuthKit user authenticates via SSO and belongs to a mapped group, the corresponding role will be set on the [organization membership](/reference/authkit/organization-membership) and reflected in the [user’s session](/authkit/sessions/integrating-sessions/access-token).
+
+> Ensure [SSO JIT provisioning](/authkit/jit-provisioning/sso-jit-provisioning) is enabled for each organization using SSO role assignment.
+
+### Enabling in Admin Portal
+
+Organization admins can assign roles to identity provider groups in the [Admin Portal](/admin-portal) during SSO or directory setup.
+
+From the _Authorization_ section in the WorkOS Dashboard, role assignment is an environment-level setting. However, it can also be configured per organization via the _Roles_ tab on that organization's page. If enabled, all Admin Portal sessions for the relevant SSO connection or directory will support group role assignment.
+
+![Enable directory group role assignment dashboard setting](https://images.workoscdn.com/images/fe19e3ac-6370-404e-9590-cdb06b3de127.png?auto=format&fit=clip&q=50)
+
+Whether to enable role assignment for SSO or directory groups depends on your application’s setup. When [provisioning users with Directory Sync](/authkit/directory-provisioning), we recommend enabling directory group role assignment due to [limitations of SSO role assignment](/sso/identity-provider-role-assignment/considerations/drawbacks).
+
+If you’re not yet using directory provisioning, you can enable SSO group role assignment as the environment default.
+
+Because this setting is configurable per organization, choose a sensible default based on your customers' typical setup:
+
+- **A. All organizations use SSO:**
+  If no organizations are using Directory Sync, enable SSO group role assignment in Admin Portal at the environment level.
+
+- **B. Some organizations use Directory Sync:**
+  Enable directory group role assignment in Admin Portal for those specific organizations.
+
+- **C. Most organizations use Directory Sync:**
+  Enable directory group role assignment in Admin Portal at the environment level, and override the setting for organizations that only use SSO.
+
+### Migrating role assignment source
+
+It’s recommended to use only one role assignment source per organization. If your organization currently uses SSO group role assignment and you'd like to switch to [directory group role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment), consider the following paths:
+
+- **A. Directory is not yet configured:**
+  [Enable directory group role assignment](/authkit/roles-and-permissions/role-assignment/enabling-in-admin-portal) for this organization via the **Roles** tab under an organization in the WorkOS Dashboard. The organization admin will be prompted to set up directory group role assignments in the Admin Portal.
+
+- **B. Directory is already configured:**
+  Manually assign roles to directory groups in the WorkOS Dashboard, or regenerate an Admin Portal link so the organization admin can set the role mappings there.
+
+Directory group role assignments take precedence and will override any SSO group role assignments on the organization membership. Once directory group roles are properly set up and reflected, you can delete the SSO group mappings.
+
+### Role source priority
+
+AuthKit enforces strict priority rules for assigning roles. When roles are sourced from SSO group role assignment:
+
+- An explicit SSO group role assignment **overrides** any role manually assigned via the [organization memberships API](/reference/authkit/organization-membership) or the [WorkOS Dashboard](https://dashboard.workos.com/). However, a default SSO group role assignment **does not override** a manual one.
+- The system may allow a temporary override through the [organization memberships API](/reference/authkit/organization-membership), but it **reapplies** the SSO-assigned role when the user next authenticates, provided the assignment came from an explicit SSO group.
+- The system **always overwrites** previous SSO role assignments with new ones, whether they originate from an explicit or default mapping.
+
+Role assignments sourced from [Directory Provisioning](/authkit/directory-provisioning):
+
+- An explicit directory group role assignment **overrides** any role manually assigned via the [organization memberships API](/reference/authkit/organization-membership) or the [WorkOS Dashboard](https://dashboard.workos.com/), or any SSO group role assignment.
+- The system **does not allow** SSO to override these roles.
+- You **can override** these roles temporarily via the [organization memberships API](/reference/authkit/organization-membership), but directory provisioning reapplies them during the next sync.
+- The system **always replaces** previous directory provisioned role assignments with new ones, regardless of whether they came from an explicit or default mapping.
+
+## Role-aware sessions
+
+When a user signs into your app, a [user session](/authkit/sessions) is initiated. The authentication response includes an access token, a JSON Web Token (JWT), with role claims indicating the user organization membership's role(s) for that session.
+
+## Organization roles
+
+Organization roles are custom roles scoped to a particular organization. They are managed via the "Roles" tab under an organization in the WorkOS Dashboard or using the [Organization Roles API](/reference/roles/organization-role).
+
+![Roles tab for organization](https://images.workoscdn.com/images/5c09cd78-041f-4bb9-9e76-f7267106b22c.png?auto=format&fit=clip&q=50)
+
+### Why might I use organization roles?
+
+In some cases, an application's fixed set of roles may not meet the needs of certain organizations. For example, an organization may require a lesser privileged set of permissions for their members. Organization roles allow you to create custom roles, with the organization's desired set of permissions, without affecting access control for other organizations.
+
+### Creating organization roles
+
+By default, organizations have no custom organization roles and simply inherit the environment-level roles. You can create an organization role by clicking the "Create role" button on the organization's "Roles" tab or using the [Organization Roles API](/reference/roles/organization-role/create). All organization role slugs are automatically prefixed with `org`.
+
+![Create an organization role](https://images.workoscdn.com/images/90f3f3c0-3c66-48b2-b962-04b34f30599e.png?auto=format&fit=clip&q=50)
+
+### Organization role configuration
+
+Once you create the first role for an organization, that organization will have its own [default role](/authkit/roles-and-permissions/configure-roles-and-permissions/default-role) and [priority order](/authkit/roles-and-permissions/configure-roles-and-permissions/priority-order), independent from the environment.
+
+New roles added to the environment will be available to the organization and placed at the bottom of the organization's role priority order.
+
+### Using organization roles
+
+Like environment-level roles, organization roles can be used in [role assignment](/authkit/roles-and-permissions/role-assignment), [sessions](/authkit/roles-and-permissions/role-aware-sessions), and the [organization membership API](/reference/authkit/organization-membership). No additional action is required to enable this behavior after creating organization roles.
+
+### Deleting an environment role
+
+When attempting to delete an environment role that's the default role for one or more organizations, you'll be prompted to select a new default role for all affected organizations. Organization members previously assigned the deleted role will be assigned the new organization default role.
+
+![Select a replacement role](https://images.workoscdn.com/images/5e6f3e51-5de5-4bb1-a850-52b2196282b9.png?auto=format&fit=clip&q=50)

package/.docs/organized/docs/{user-management → authkit}/sessions.mdx

@@ -2,12 +2,12 @@
 title: Sessions
 description: Learn more about integrating sessions.
 showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/sessions.mdx
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/sessions.mdx
 ---
 
 ## Introduction
 
-When a user signs in to your app, a user session is created. Along with the [User object](reference/user-management/user), a successful authentication response will include an access token and refresh token. Your application can use these tokens to ensure that the user’s session is still active.
+When a user signs in to your app, a user session is created. Along with the [User object](/reference/authkit/user), a successful authentication response will include an access token and refresh token. Your application can use these tokens to ensure that the user’s session is still active.
 
 Each user session can be viewed from within the WorkOS dashboard:
 
@@ -25,7 +25,7 @@ Successful authentication responses will include both an access token and a refr
 
 If you’re using our [Next SDK](https://www.npmjs.com/package/@workos-inc/authkit-nextjs) or [Remix SDK](https://github.com/workos/authkit-remix), all the work of validating access tokens and refreshing expired tokens is handled for you (more framework support coming soon). Read on for details about how token handling works.
 
-The access token is a JSON Web Token (JWT), which should be validated on each request using a library like jose. The [signing JWKS](/reference/user-management/session-tokens/jwks) can be found at `http://api.workos.com/sso/jwks/<clientId>`. The JWT includes the following claims:
+The access token is a JSON Web Token (JWT), which should be validated on each request using a library like jose. The [signing JWKS](/reference/authkit/session-tokens/jwks) can be found at `http://api.workos.com/sso/jwks/<clientId>`. The JWT includes the following claims:
 
 - `sub`: the WorkOS user id
 - `sid`: the session ID (used for signing out)
@@ -38,13 +38,13 @@ The access token is a JSON Web Token (JWT), which should be validated on each re
 
 ### Refresh Token
 
-Refresh tokens should be persisted on the backend in, for instance, a database, cache, or secure http-only cookie. A new access token can be obtained by using the [authenticate with refresh token](/reference/user-management/authentication/refresh-token) endpoint. If the session is still active, a new access token and refresh token will be returned. Refresh tokens are single use, so be sure to replace the old refresh token with the newly generated one.
+Refresh tokens should be persisted on the backend in, for instance, a database, cache, or secure http-only cookie. A new access token can be obtained by using the [authenticate with refresh token](/reference/authkit/authentication/refresh-token) endpoint. If the session is still active, a new access token and refresh token will be returned. Refresh tokens may be rotated after use, so be sure to replace the old refresh token with the newly returned one.
 
 ### Switching Organizations
 
-Refresh tokens can be used to obtain a new access token for a different organization by passing the `organization_id` parameter to the [authenticate with refresh token](/reference/user-management/authentication/refresh-token) endpoint. If the session for the refresh token is authorized to access the organization, then the `org_id` will be set to the given organization, along with the `role` and `permissions` claims matching the user's membership in that organization.
+Refresh tokens can be used to obtain a new access token for a different organization by passing the `organization_id` parameter to the [authenticate with refresh token](/reference/authkit/authentication/refresh-token) endpoint. If the session for the refresh token is authorized to access the organization, then the `org_id` will be set to the given organization, along with the `role` and `permissions` claims matching the user's membership in that organization.
 
-If the user is not authorized for the organization, then an appropriate [authentication error](/reference/user-management/authentication-errors) will be returned and the user will need to authenticate. Applications using [AuthKit](/user-management/authkit) can use the [Get Authorization URL](/reference/user-management/authentication/get-authorization-url) and the `organization_id` parameter to initiate the authentication flow specifically for the organization.
+If the user is not authorized for the organization, then an appropriate [authentication error](/reference/authkit/authentication-errors) will be returned and the user will need to authenticate. Applications can use the [Get Authorization URL](/reference/authkit/authentication/get-authorization-url) and the `organization_id` parameter to initiate the authentication flow specifically for the organization.
 
 ### Signing Out
 
@@ -52,7 +52,7 @@ When a user signs out of your app, the following steps should occur:
 
 - Get the session id (`sid` claim) out of the access token.
 - Delete the user’s app session.
-- Redirect the user’s browser to [logout endpoint](/reference/user-management/logout) endpoint (this will ensure the user’s session ends at WorkOS).
+- Redirect the user’s browser to [logout endpoint](/reference/authkit/logout) endpoint (this will ensure the user’s session ends at WorkOS).
 - The user will be redirected back to the URL configured as your _App homepage URL_
 
 #### Example
@@ -74,28 +74,40 @@ redirect(workos.userManagement.getLogoutUrl({ sessionId }));
 
 Using the WorkOS dashboard you can configure how Sessions work in your integration. You’ll find the settings in the _Authentication_ section.
 
-![Session Configuration UI](https://images.workoscdn.com/images/158987a3-127c-4bcd-a3ac-53b1be0abd8a.png?auto=format&fit=clip&q=50)
+![Session Configuration UI](https://images.workoscdn.com/images/88bde63e-e30c-4221-9c3b-94ec693dda4b.png?auto=format&fit=clip&q=50)
 
 - **Maximum session length:** The session will expire after this length of time. Once expired the user will need to sign in again.
-- **Access token duration:** Your backend can verify the access token on each request (see the [Integrating Sessions](user-management/sessions/integrating-sessions) section above). It’s recommended to keep the access token duration short so that changes in the session are quickly reflected in your app.
+- **Access token duration:** Your backend can verify the access token on each request (see the [Integrating Sessions](/authkit/sessions/integrating-sessions) section above). It’s recommended to keep the access token duration short so that changes in the session are quickly reflected in your app.
 - **Inactivity timeout:** The session ends if a refresh has not occurred in this length of time. The user will need to sign in again.
 
 Additionally, make sure to review your settings in the _Redirect_ section:
 
-### Logout redirect
+### Sign-out redirect
 
-![Logout redirect settings](https://images.workoscdn.com/images/8605a0d5-8968-409e-90af-cca4e56247ed.png?auto=format&fit=clip&q=80)
+![Sign-out redirect settings](https://images.workoscdn.com/images/810c26ed-e6d3-4177-a137-5478870316b5.png?auto=format&fit=clip&q=50)
 
-Make sure to set a default Logout URI, which will be the location users will be redirected to after their session has been ended. Non-default Logout URIs can be used as values to the `return_to` parameter of the [Logout API](/reference/user-management/logout/get-logout-url) in order to dynamically choose the final logout redirect location.
+Make sure to set a default Sign-out redirect, which will be the location users will be redirected to after their session has been ended. Non-default Sign-out redirects can be used as values to the `return_to` parameter of the [Logout API](/reference/authkit/logout/get-logout-url) in order to dynamically choose the final logout redirect location.
 
 #### Wildcards
 
-The `*` symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules in order to properly function.
+WorkOS supports using wildcard characters (`*`) in sign-out redirects to handle dynamic subdomains or variable ports during development.
 
-- Wildcard Logout URIs can only be created in staging environments.
-- The protocol of the URL **must** be either `http:` or `https:`. For example, `com.example.app://*.example.com` will not work.
-- The wildcard **must** be located in a subdomain within the hostname component. For example, `http://*.com` will not work.
-- The wildcard **must** be located in the subdomain which is furthest from the root domain. For example, `https://sub.*.example.com` will not work.
-- The URL **must not** contain more than one wildcard. For example, `https://*.*.example.com` will not work.
-- A wildcard character **may** be prefixed and/or suffixed with additional valid hostname characters. For example, `https://prefix-*-suffix.example.com` will work.
-- A URL with a valid wildcard **will not** match a URL more than one subdomain level in place of the wildcard. For example, `https://*.example.com` will not work with `https://sub1.sub2.example.com`.
+##### Subdomains
+
+The `*` symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules:
+
+- The protocol of the URL **must not** be `http:` in production environments.
+- The wildcard **must** be located in the subdomain furthest from the root domain (e.g., `https://*.sub.example.com` will work, but `https://sub.*.example.com` will not).
+- The URL **must not** contain more than one wildcard.
+- A wildcard character **may** be prefixed and/or suffixed (e.g., `https://prefix-*-suffix.example.com`).
+- A wildcard **will not** match across multiple subdomain levels (e.g., `https://*.example.com` will not match `https://sub1.sub2.example.com`).
+- Wildcards cannot be used with [public suffix domains](https://publicsuffix.org) (e.g., `https://*.ngrok-free.app` will not work).
+- The wildcard will match letters, digits, hyphens, and underscores.
+- A URL with a wildcard cannot be set as the default sign-out redirect.
+
+##### Ports
+
+To support [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) ("OAuth 2.0 for Native Apps") and local development, a wildcard may be used in place of the port number.
+
+- This is strictly limited to `localhost` and loopback IP addresses (e.g., `127.0.0.1`).
+- Example: `http://localhost:*/signed-out` is valid.

package/.docs/organized/docs/{user-management → authkit}/social-login.mdx

@@ -2,7 +2,7 @@
 title: Social Login
 description: Quickly and easily integrate with social OAuth providers.
 showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/social-login.mdx
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/social-login.mdx
 ---
 
 ## Introduction
@@ -25,10 +25,24 @@ After a provider has been configured and enabled, it will appear as a sign in op
 
 ![AuthKit sign in page with social providers highlighted](https://images.workoscdn.com/images/f743cf4f-a32c-464b-94a4-db9f5c146773.png?auto=format&fit=clip&q=80)
 
+## Custom OAuth scopes
+
+AuthKit offers support for custom OAuth scopes for Google, Microsoft, GitHub, GitLab, and Xero integrations. This allows you to request specific permissions when accessing user profile data from these providers. For instance, requesting access to read Google Calendar events or retrieve emails from a Microsoft account. See the relevant provider section for more information:
+
+- [Google](/integrations/google-oauth/configure-additional-oauth-scopes-optional)
+- [Microsoft](/integrations/microsoft-oauth/configure-additional-oauth-scopes-optional)
+- [GitHub](/integrations/github-oauth/configure-additional-oauth-scopes-optional)
+- [GitLab](/integrations/gitlab-oauth/configure-additional-oauth-scopes-optional)
+- [Xero](/integrations/xero-oauth/configure-additional-oauth-scopes-optional)
+
+## Provider-driven user profile updates
+
+When a user logs in with a social provider, the user profile information may be updated. The user's profile picture and name will always be updated to match the information supplied by the social provider. If the email address at the provider has changed and the user is only linked to a single provider, the email will also be updated to match. If the new email is already in use, no change will take place.
+
 ---
 
 ## Integrating via the API
 
-If you’d prefer to build and manage your own authentication UI, you can do so via the User Management [Authentication API](/reference/user-management/authentication).
+If you'd prefer to build and manage your own authentication UI, you can do so via the AuthKit [Authentication API](/reference/authkit/authentication).
 
 Examples of building custom UI are also [available on GitHub](https://github.com/workos/authkit).

package/.docs/organized/docs/{user-management → authkit}/sso-with-contractors.mdx

@@ -2,8 +2,7 @@
 title: SSO with contractors
 description: Enforcing organization SSO access with external contractors.
 showNextPage: true
-originalPath: >-
-  .tmp-workos-clone/packages/docs/content/user-management/sso-with-contractors.mdx
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/sso-with-contractors.mdx
 ---
 
 ## Introduction
@@ -29,7 +28,7 @@ Adding SSO to your application is a straightforward process when using AuthKit,
 
 (2) Configure a callback endpoint in your application
 
-(3) Add your endpoint URL as a sign-in callback in the WorkOS dashboard
+(3) Add your endpoint URL as a redirect URI in the WorkOS dashboard
 
 (4) Handle the user session and grant access to the application
 
@@ -55,7 +54,7 @@ When the user logs in, they will move through the following flow:
 
 (5) Access is provisioned by the application
 
-More in-depth information on configuration can be found in the [Single Sign-On section](/user-management/sso), with AuthKit implementation guidance available in the [Quick Start guide](/user-management).
+More in-depth information on configuration can be found in the [Single Sign-On section](/authkit/sso), with AuthKit implementation guidance available in the [Quick Start guide](/authkit).
 
 ## Understanding authentication policies
 

package/.docs/organized/docs/{user-management → authkit}/sso.mdx

@@ -4,7 +4,7 @@ description: >-
   Facilitate greater security, easier account management, and accelerated
   application onboarding and adoption.
 showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/sso.mdx
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/sso.mdx
 ---
 
 ## Introduction
@@ -91,6 +91,6 @@ The setup instructions you’ve seen in the Admin Portal are also available dire
 
 ## Integrating via the API
 
-If you’d prefer to build and manage your own authentication UI, you can do so via the User Management [Authentication API](/reference/user-management/authentication).
+If you'd prefer to build and manage your own authentication UI, you can do so via the AuthKit [Authentication API](/reference/authkit/authentication).
 
 Examples of building custom UI are also [available on GitHub](https://github.com/workos/authkit).

package/.docs/organized/docs/authkit/users-organizations.mdx

@@ -0,0 +1,107 @@
+---
+title: Users and Organizations
+description: Flexible application modeling with user and membership features.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/users-organizations.mdx
+---
+
+## Users
+
+The [User object](/reference/authkit/user) represents an identity that has access or owns artifacts in your application. A User object may not uniquely identify an individual person, since a person may present themselves as having multiple identities in the same system.
+
+What uniquely identifies a user is their **email address**, since having access to that email inbox ultimately gives access to all accounts based on that address.
+
+### Authentication methods
+
+There may be multiple authentication methods on a single user object, such as [Email + Password](/authkit/email-password) or [OAuth](/authkit/social-login). A user can sign in with any of the authentication methods associated with them, as long as you have enabled those authentication methods in the WorkOS Dashboard.
+
+<UserManagementDiagrams.AuthenticationMethods />
+
+### Identity linking
+
+Because a user is uniquely identified by their email address, you won’t have users with duplicate email addresses. WorkOS handles [identity linking](/authkit/identity-linking) automatically.
+
+### Email verification
+
+All users will go through an initial [email verification process](/authkit/email-verification) by default.
+
+This applies to all authentication methods, including OAuth and SSO. This unifying interface simplifies how your application considers the authenticity of your users.
+
+### Domain verification
+
+If a user’s email domain matches a verified organization domain when signing in with SSO, they will [automatically be considered verified](/authkit/domain-verification) and will not need to go through the email verification flow.
+
+---
+
+## Organizations
+
+Organizations represent both a collection of users that your customer’s IT admin has control over and a workspace within which members collaborate. Organizations are a first-class concept in WorkOS and support a suite of features around organizational management. There is no limit to the number of organizations you can create in WorkOS.
+
+### Organization memberships
+
+An organization contains users as members. Organization membership allows you to model organizations as "workspaces" and user’s access to them with memberships.
+
+WorkOS organization memberships are designed to be flexible, and support any B2B app model. For example:
+
+<UserManagementDiagrams.UserToOrganizationRelationships />
+
+- **Multiple Workspaces:** A self-serve productivity app, like Figma, where each user can be in any number of organizations, can create their own workspace and join any number of other workspaces.
+- **Single Workspace:** An app that has no collaboration outside a customer’s company, like an employee survey tool, where each user is in exactly one organization.
+
+While these are two distinct models, your choice may depend on your go-to-market strategy, which may change over time. **WorkOS AuthKit supports both**.
+
+### Organization access
+
+It’s common for users to create resources in B2B applications. You can use the organization as a container for these resources, so that access is dependent on a user’s access to the organization.
+
+This means when a user leaves an organization and is no longer a member, the data remains with the organization and not the user. Organizations provide the level of data ownership that B2B applications structure around.
+
+While organization membership conveys the most basic form of access, you can attach more granular role information per member within your own application’s database.
+
+### Organization roles
+
+In addition to the [environment-level roles](/authkit/roles-and-permissions/configure-roles-and-permissions), organizations can define their own custom roles, which are assignable only within the context of the organization. Refer to the [organization roles documentation](/authkit/roles-and-permissions/organization-roles) for more details.
+
+### Membership management
+
+If your application uses a soft-delete model, you can utilize the extended organization membership lifecycle. Organization memberships have three possible statuses:
+
+- `pending`, when a user is invited to an organization
+- `active`, when a user is added as an organization member or accepts an invitation
+- `inactive`, when an organization membership is deactivated
+
+For soft-delete use cases, we also provide deactivation and reactivation APIs:
+
+- [Deactivating an organization membership](/reference/authkit/organization-membership/deactivate) sets its status to `inactive` and revokes all active [sessions](/authkit/sessions). Note `pending` memberships cannot be deactivated and should be deleted using the [deleting membership API](/reference/authkit/organization-membership/delete) instead.
+- [Reactivating an organization membership](/reference/authkit/organization-membership/reactivate) sets its status to `active` and retains the role attached to the organization membership prior to deactivation. This role can be updated using the [update organization membership API](/reference/authkit/organization-membership/update). Note `pending` memberships cannot be reactivated. For this the user should go through the [invitation acceptance flow](/authkit/invitations) instead. If invitations are not needed, the organization membership can be [created as active directly](/reference/authkit/organization-membership/create).
+
+If your application uses a hard-delete model, you may use organization memberships without deactivation/reactivation by [deleting memberships](/reference/authkit/organization-membership/delete) for users who should no longer have access to an organization.
+
+### When to use deletion vs. deactivation
+
+Hard deletion is preferred if the app has no need to "remember" the membership. For example, when members operate solely on customer data and have no data of their own. When a member of the organization is gone, there's no need to keep around their membership data. An app in this case may even want to entirely [delete the User](/reference/authkit/user/delete) once the membership is deleted.
+
+Deactivation may be preferred in cases where a member retains some data after leaving the organization, for example: messages, documents, or other data which reference that member. It also allows for building a user interface to list former members, perhaps with the option to reactivate them.
+
+### Automated memberships
+
+Beyond manually adding or removing users to and from organizations as members, users can be automatically [Just-in-Time (JIT) provisioned](/authkit/jit-provisioning) into an organization if their email address matches one of the organization's [verified domains](/authkit/domain-verification). This allows customers to quickly onboard teammates.
+
+Users can also [invite individuals to organizations](/authkit/invitations), regardless of their email domain. This is handy for contractors within a company, or a collection of people without a shared domain.
+
+### Creating organizations for new users
+
+In some applications, all activity should happen within the context of an organization. This pattern is common in B2B applications where:
+
+- All features and data are scoped to an organization
+- Users need to be associated with an organization to use the application
+
+For these applications, when new users don't already belong to an organization via [Just-in-Time provisioning](/authkit/jit-provisioning) or an [invitation](/authkit/invitations), you'll want to create an organization for them.
+
+To ensure all users have at least one organization:
+
+1. **Check the access token**: When AuthKit redirects a user to your application after sign up or sign in, check whether the [access token](/authkit/sessions/integrating-sessions/access-token) contains an `org_id`
+2. **Present organization creation form**: If no organization is present, show the user a form with a name field to create a new organization
+3. **Create the organization**: On form submission, use the [create organization API](/reference/organization/create) to create the organization
+4. **Create organization membership**: Use the [create organization membership API](/reference/authkit/organization-membership/create) to add the user as a member of the new organization
+5. **Refresh the token**: Call the [authenticate with refresh token API](/reference/authkit/authentication/refresh-token) with the new organization ID to receive a new access token that includes the organization

package/.docs/organized/docs/custom-domains/admin-portal.mdx

@@ -13,8 +13,6 @@ While developing with WorkOS in a staging environment, users will see the `setup
 
 In production environments, users will see `setup.workos.com` by default or a custom domain if configured.
 
-> You must configure an [Authentication API domain](/custom-domains/auth-api) first in order for your custom Admin Portal domain to work properly.
-
 ### (1) Navigate to Domains configuration
 
 With the production environment selected, navigate to the _Domains_ section of the [WorkOS Dashboard](https://dashboard.workos.com/).

package/.docs/organized/docs/custom-domains/authkit.mdx

@@ -11,8 +11,6 @@ The domain for AuthKit will consist of a randomly generated phrase plus the doma
 
 This is the default in the staging environment, in Production environments a custom domain can be configured via the dashboard.
 
-> You must configure an [Authentication API domain](/custom-domains/auth-api) first in order for your custom AuthKit domain to work properly.
-
 ### (1) Navigate to Domains configuration
 
 With the production environment selected, navigate to the _Domains_ section of the [WorkOS Dashboard](https://dashboard.workos.com/).

package/.docs/organized/docs/custom-domains/email.mdx

@@ -7,14 +7,14 @@ originalPath: .tmp-workos-clone/packages/docs/content/custom-domains/email.mdx
 
 ## Configuring a domain
 
-Several User Management features require sending emails:
+Several AuthKit features require sending emails:
 
 - Magic Auth
 - Email verification
 - Password resets
 - Invitations
 
-While developing with WorkOS in a staging environment, WorkOS will send User Management emails from `workos.dev`.
+While developing with WorkOS in a staging environment, WorkOS will send AuthKit emails from `workos.dev`.
 
 In production environments, emails are sent from a custom domain when configured or from `workos-mail.com` by default.
 

package/.docs/organized/docs/deprecations/_navigation.mdx

@@ -0,0 +1,8 @@
+---
+title: Deprecations
+links:
+  - title: Migrate from raw_attributes
+    url: /deprecations/raw-attributes
+originalPath: .tmp-workos-clone/packages/docs/content/deprecations/_navigation.mdx
+---
+