@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/user-management/connect.mdx

@@ -1,110 +0,0 @@
----
-title: WorkOS Connect
-description: Enable other applications to access your user's identities.
-showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/connect.mdx
----
-
-## Introduction
-
-WorkOS Connect is a set of controls and APIs that developers can use to allow different types of applications to make use of your users' identity and resources. Connect is built on top of industry-standard specifications like OAuth 2.0 and OpenID Connect in order to support many common use-cases out of the box.
-
-## Getting started
-
-Each Connect integration is defined as an Application, which can be created inside of the [WorkOS Dashboard](/dashboard).
-
-When creating an application, you choose the type of integration: OAuth or Machine-to-Machine (M2M). You also choose the level of trust: first-party or third-party.
-
-### OAuth applications
-
-Select OAuth when clients will be web-browsers or mobile-applications and the expected subject of the authentication is a [User](/reference/user-management/user). Integrating with an OAuth application uses the underlying `authorization_code` OAuth flow which is supported by many libraries and frameworks out of the box.
-
-Upon successful authorization, the issued tokens will contain information about the user who signed in.
-
-### M2M applications
-
-Select M2M when clients will be other machines, such as one of your customer's applications. Integrating with an M2M application uses the underlying `client_credentials` flow.
-
-Unlike an OAuth application, the subject of the authorization is not an individual. Instead issued access tokens will contain an `org_id` claim which represents the customer you are granting access to via the M2M application.
-
-A common use-case for M2M applications is using its credentials as API access credentials for specific customers and partnerships.
-
-### First-party applications
-
-Select first-party when the client is one that your team controls, such as supporting services that are deployed separately from your main application but still need access to your users' identities. Examples include community forums or customer support portals.
-
-### Third-party applications
-
-Select third-party when the client is one of your customers or partners, but you do not directly control the integrating application. For this reason, you must also associate third-party applications with an [Organization](/reference/organization) that represents the customer or partner.
-
-A third-party _OAuth_ application will generally have a "Sign in with [your application]" button on their login page, in the same way many sites have a "Sign in with Google" button, allowing you to offer similar functionality to your customers or partners. Unlike first-party applications, your users will be prompted in AuthKit to explicitly authorize the application before their identity is shared.
-
-![Screenshot of the application authorization screen in AuthKit.](https://images.workoscdn.com/images/b102d7de-4ceb-4e3c-a313-de2cad632449.png)
-
-A third-party _M2M_ application will generally be a service you are authorizing to access your application's API using the access tokens obtained via the `client_credentials` flow covered below.
-
-> Machine-to-machine applications can only be configured as third-party.
-
-## Configuring applications
-
-Once you've created an application, you can configure the following settings.
-
-### Redirect URI
-
-For OAuth applications, this is the final location users will be redirected to after successful authentication. Clients should use the [Token Endpoint](/reference/workos-connect/token) to exchange the `code` for tokens at this location.
-
-### Name and Logo
-
-For third-party OAuth applications, the name and logo will be displayed to your users when they are prompted to authorize access. Both light and dark-mode logos are supported.
-
-### Credentials
-
-Applications can have up to 5 credentials. These are only shown once upon creation and do not expire. The application `client_id` and `client_secret` from a credential can be used to authenticate to the [OAuth-based Connect APIs](/reference/workos-connect).
-
-When sharing third-party app credentials with an external party, use a secure method — like encrypted email or file sharing — and make sure the recipient is properly authenticated.
-
-## Authentication
-
-When using Connect, there are two sides of the integration with each Application:
-
-- **The requesting client**: the client (an external application) that receives Connect-issued tokens, receiving identity information and optionally using access tokens to make requests to your API.
-- **The resource server**: the service (generally your app) that allows other clients to authenticate with the Connect-issued tokens.
-
-In the next sections we will cover the relevant APIs for each party.
-
-## Receiving Tokens
-
-After an external application has been issued credentials from a Connect Application, it can receive identity and/or access tokens depending on the type of Application.
-
-### M2M tokens
-
-Machine-to-machine applications can use the `client_credentials` grant type with the [Token Endpoint](/reference/workos-connect/token) to obtain an `access_token` to authenticate calls to your API.
-
-<CodeBlock
-  title="Obtain access token"
-  file="connect-client-credentials-example"
-/>
-
-Since machine-to-machine applications are associated with a particular organization, its issued access tokens contain an `org_id` claim that your application's API can use to control access.
-
-### OAuth tokens
-
-OAuth applications use the OAuth 2.0 `authorization_code` flow and also conform to the OpenID Connect (OIDC) spec, allowing external applications to receive tokens associated with a particular user.
-
-Many OAuth and OIDC libraries support Connect applications out of the box needing only configuration:
-
-<CodeBlock>
-  <CodeBlockTab file="connect-oauth-configuration.passport" title="Passport" />
-  <CodeBlockTab file="connect-oauth-configuration.omniauth" title="OmniAuth" />
-</CodeBlock>
-
-## Verifying Tokens
-
-Your application can verify the tokens sent by external applications for the purpose of authenticating requests using the JWKS for your environment. The process is similar to validating the access token JWT provided by an AuthKit login.
-
-<CodeBlock>
-  <CodeBlockTab file="connect-access-token-verification.oauth" title="OAuth" />
-  <CodeBlockTab file="connect-access-token-verification.m2m" title="M2M" />
-</CodeBlock>
-
-In addition to fast stateless verification, you can use the [Token Introspection API](/reference/workos-connect/introspection) to synchronously check whether a token is still valid.

package/.docs/organized/docs/user-management/directory-provisioning.mdx

@@ -1,78 +0,0 @@
----
-title: Directory Provisioning
-description: Manage users and organization memberships via directory sync providers.
-showNextPage: true
-originalPath: >-
-  .tmp-workos-clone/packages/docs/content/user-management/directory-provisioning.mdx
----
-
-> Please reach out to [support@workos.com](mailto:support@workos.com) or via your team’s WorkOS Slack channel if you would like Directory Provisioning enabled.
-
-## Introduction
-
-Directory provisioning gives IT admins full control over user and membership management, eliminating the need for manually adding or removing members. Users from a directory are pre-provisioned and managed by their [Identity Provider](/glossary/idp).
-
-## Initial configuration
-
-A [Directory Sync](/directory-sync) integration will need to be configured for every organization that wants to source users and memberships via directory provisioning. Directories can be set up via the [WorkOS Dashboard](https://dashboard.workos.com/) with [Setup Links](/admin-portal/a-setup-link-from-workos-dashboard). You can also [integrate the Admin Portal with your app](/admin-portal/b-integrate-with-your-app) to generate links to configure directories.
-
-### Supported directory providers
-
-The following directory sync providers are supported with directory provisioning:
-
-- Okta SCIM
-- Entra ID (Azure AD) SCIM
-- Google Workspace
-- OneLogin SCIM
-- CyberArk SCIM
-- PingFederate SCIM
-- JumpCloud SCIM
-- Rippling SCIM
-- Generic SCIM
-
-> If you are interested in directory provisioning support from a directory sync provider not listed above, please reach out to [support@workos.com](mailto:support@workos.com) or via your team’s WorkOS Slack channel.
-
-## Provision users from a directory
-
-Users provisioned through a directory with an email domain matching a verified organization domain will be automatically added as members of the organization, without needing an invitation.
-
-Other users are created with `pending` memberships and receive an email [invitation](/user-management/invitations) to join the organization. Pending members cannot sign in until the invitation is accepted, at which point they become active organization members.
-
-> [Invitation emails](/user-management/custom-emails/disabling-default-emails) can be disabled if you prefer to manage invitations with a custom approach.
-
-## Manage users from a directory
-
-In addition to provisioning new users, any updates to existing users and de-provisioning events will be reflected in User Management.
-
-Users with email addresses matching one of the organization’s verified domains are fully managed by the directory. Updates to their attributes from the directory will override changes made through SSO, the API, or manually in the dashboard.
-
-> If multiple organizations with directory provisioning contain the same verified domain, the user's name will always reflect the most recent directory update.
-
-Other users, with email domains not verified by the organization, will not be fully managed by the directory, so updates made via SSO, API, or manually in the dashboard will persist.
-
-When a user is de-provisioned in the directory, the [status](/reference/user-management/organization-membership) of their corresponding organization membership will be set to `inactive`. While the user will no longer be able to sign in to the organization, the membership and user are not automatically deleted.
-
-If a user is re-provisioned in the directory, their organization membership will be reactivated with its previous role and its [status](/reference/user-management/organization-membership) will be set to `active`.
-
-## Directory provisioning actions
-
-Below is a list of directory provisioning and deprovisioning actions and the corresponding changes triggered in User Management. If you're using standalone Directory Sync, refer to the [standalone Directory Sync documentation](/directory-sync/api-overview/directory).
-
-| Directory Action             | Changes triggered in WorkOS                                                                                                                                                                                                                                                     | Event(s) Emitted                                                                                 |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| Directory user provisioned   | [User](/reference/user-management/user) and [organization membership](/reference/user-management/organization-membership) objects created.                                                                                                                                      | [user.created](/events/user), [organization_membership.created](/events/organization-membership) |
-| Directory user info updated  | If the user's email domain matches one of the organization's verified domains, any updates to the user's name will be reflected on the [user](/reference/user-management/user) object. Otherwise, the user object will not be modified. User email address is always immutable. | [user.updated](/events/user)                                                                     |
-| Directory user deprovisioned | Organization membership deactivated and all sessions for the user are revoked. Their role is reset to the default role.                                                                                                                                                         | [organization_membership.updated](/events/organization-membership)                               |
-| Directory user reactivated   | Organization membership reactivated.                                                                                                                                                                                                                                            | [organization_membership.updated](/events/organization-membership)                               |
-
----
-
-## Frequently asked questions
-
-### I am using directory provisioning, but some directory users aren't being provisioned in User Management. Why would a directory user not be provisioned in User Management?
-
-Directory users need to have a primary email address to be provisioned in User Management. If the directory user is missing a primary email, they won't be provisioned. Additionally, if the primary email of a directory user is shared by another directory user, only one will be provisioned in User Management, as emails are unique to User Management users.
-
-### If a user's email is changed in the directory, will this change be reflected on the user's email in WorkOS?
-
-The email address on the [User object](/reference/user-management/user) is immutable, but the email on the underlying [directory user](/reference/directory-sync/directory-user) object will be modified.

package/.docs/organized/docs/user-management/email-verification.mdx

@@ -1,29 +0,0 @@
----
-title: Email Verification
-description: Learn more about the email verification process.
-showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/email-verification.mdx
----
-
-## Introduction
-
-Email verification is a process in which a new user must validate ownership of their email inbox before they can access the application, ensuring authenticity of inbox ownership.
-
-## The email verification flow
-
-Verification is a two-step process:
-
-- A user signs up to your application and an email is sent with a verification code.
-- The user inputs the verification code to complete the signup process.
-
-This applies to all authentication methods including [OAuth](/user-management/social-login) and [SSO](/user-management/sso). This unifying interface simplifies how your application considers the authenticity of your users.
-
-**Email verification is always on** to ensure that verified users are always returned to your application.
-
-## Users with verified email domains
-
-Users signing in with SSO with a [verified domain](/user-management/domain-verification) are automatically considered verified and do not need to complete the email verification process.
-
-## Sending verification emails
-
-[AuthKit](/user-management) automatically handles email verification out of the box. When a user signs up via the hosted signup form, AuthKit will automatically send the verification email, prompt the user to input the code and route them through the authentication process before they gain access to the application. If desired, you can [send these emails yourself](/user-management/custom-emails).

package/.docs/organized/docs/user-management/entitlements.mdx

@@ -1,46 +0,0 @@
----
-title: Entitlements
-description: >-
-  Connect your WorkOS account to Stripe and automatically provision access
-  tokens with entitlements.
-showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/entitlements.mdx
----
-
-## Introduction
-
-Entitlements are a way to provision an account in your application with specific features or functionality based on the subscription plan a user is on. For example, you might have an “Enterprise” plan that allows users to access certain features like [Audit Logs](/audit-logs), and a “Basic” plan that does not.
-
-The WorkOS Entitlements integration makes it easy to get Stripe's entitlement information into your application without needing to listen to Stripe webhooks or explicitly track them in your application.
-
----
-
-## (1) Connect your WorkOS account to Stripe
-
-WorkOS uses [Stripe Connect](https://stripe.com/connect) to connect your WorkOS account to your Stripe account. This allows WorkOS to listen to Stripe webhooks on your behalf and keep your users’ entitlements up-to-date.
-
-Entitlements can be enabled in the _Authentication_ section of the [WorkOS Dashboard](https://dashboard.workos.com/). Clicking _Connect_ will open a new tab on Stripe where you can approve the connection. Once that’s complete, close the tab.
-
-![A screenshot showing the Stripe entitlements card in the WorkOS Dashboard](https://images.workoscdn.com/images/e4da96e3-3e00-4d66-aa2c-14d4114e96f0.png?auto=format&fit=clip&q=50)
-
-If you decide to disconnect your Stripe account later, you can do so from the same section. Clicking the _Manage_ button will clear out any entitlement data stored in WorkOS and the `entitlements` claim will no longer be included in access tokens.
-
----
-
-## (2) Set organizations’ Stripe customer IDs
-
-WorkOS needs one more piece of information to include entitlements in the access token: the Stripe customer ID for each organization.
-
-Once you have a WorkOS organization ID and a Stripe customer ID, you can set the Stripe customer ID for the organization. One way to handle this is to create a Stripe customer and then set the created Stripe customer ID on the WorkOS organization before redirecting the user to a Stripe checkout page or billing portal. This can be done via the WorkOS API or SDK. Here’s an example using the SDK:
-
-<CodeBlock file="configure-organization-with-stripe-customer-id" />
-
----
-
-## Use the entitlements in your application
-
-The access token will now include the `entitlements` claim, containing the user’s entitlements. You can use this information to gate access to features in your application.
-
-Entitlements will show up in the access token the next time the user logs in or the session is refreshed. You can manually [refresh the session](reference/user-management/authentication/refresh-token) after the user has completed their subscription purchase. Here's an example in Express:
-
-<CodeBlock file="session-entitlements-example" />

package/.docs/organized/docs/user-management/jit-provisioning.mdx

@@ -1,36 +0,0 @@
----
-title: Just-in-time Provisioning
-description: Automatically provision users and memberships with JIT provisioning.
-showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/jit-provisioning.mdx
----
-
-## Introduction
-
-JIT provisioning automatically creates users and organization memberships when a user signs in for the first time. This feature allows users to access an organization’s resources without requiring manual invitations from the IT admin.
-
-## Automatically add users with verified domains as members
-
-Users with [verified email domains](/user-management/domain-verification) can be automatically added as members to an organization through the organization's [domain policy](/user-management/organization-policies/domain-policy). This feature is useful when an application or organization wants to automatically group individuals into the same workspace based on their email domain.
-
-![Configuring a domain policy in the dashboard](https://images.workoscdn.com/images/b98493d9-f9fe-475d-a448-f9099558cd19.png?auto=format&fit=clip&q=50)
-
-## SSO JIT provisioning
-
-When a user signs in for the first time, WorkOS detects when their email domain matches a verified domain of an organization and prompts the user to sign in through the organization's IdP. This user is then automatically created and added as a member to the organization.
-
-![Configuring just-in-time provisioning for SSO users in the dashboard](https://images.workoscdn.com/images/90a85516-ed7a-4bd4-88a5-384b2f818436.png?auto=format&fit=clip&q=50)
-
-### Guest provisioning
-
-SSO JIT provisioning is not fully supported for guests whose email domain has not been [verified](/user-management/domain-verification) by the organization.
-
-For example, an IT admin may want to gate all contractor access through their IdP (to enable access revocation across applications) but the contractor prefers to use their own email address.
-
-Instead, guest users must be [invited](/user-management/invitations) to join the organization before they are able to sign in with the organization's IdP.
-
-## Disabling JIT provisioning
-
-Both automatic membership by email domain and SSO JIT provisioning are enabled by default but can be disabled in the [WorkOS Dashboard](https://dashboard.workos.com).
-
-Disabling these features may be useful if the IT admin prefers to manually control membership through [invitations](/user-management/invitations).

package/.docs/organized/docs/user-management/overview.mdx

@@ -1,46 +0,0 @@
----
-title: User Management
-description: >-
-  Easy to use authentication APIs designed to provide a flexible, secure, and
-  fast integration.
-showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/overview.mdx
----
-
-## Introduction
-
-WorkOS User Management is a set of user authentication and organization security features that securely power your application. Features are designed to be flexible, while offering a fast integration to handle all of the user management complexity that comes with advanced business and customer needs.
-
-## Authentication
-
-User Management supports many authentication methods out of the box. They are designed to grow with your app, from the simplest use case all the way to complex Enterprise [SSO](/user-management/sso) for your largest customers, these include:
-
-- [Single Sign-On](/user-management/sso)
-- [Email & Password](/user-management/email-password)
-- [Social Login](/user-management/social-login)
-- [Multi-Factor Auth](/user-management/mfa)
-- [Magic Auth](/user-management/magic-auth)
-
-These features are available via [AuthKit](/user-management), or through the public [API](/reference/user-management). AuthKit provides an easy to integrate, pre-built authentication flow, while integrating against the API allows you to implement your own UI and Sign In flow.
-
-## Fast integration
-
-The fastest way to integrate WorkOS User Management features is with [AuthKit](/user-management).
-
-![AuthKit Sign In UI](https://images.workoscdn.com/images/b8286e7e-3ad9-4d43-99d5-e022e6bb36fb.png?auto=format&fit=clip&q=80)
-
-AuthKit abstracts away many of the UX and WorkOS API calling concerns automatically, allowing you to focus on building your application. See the [Quick Start](/user-management) guide for more information on how to get started.
-
-## Security
-
-Adopting User Management in your app provides a wealth of security benefits.
-
-- Best-in-class [email verification](/user-management/email-verification), enabled by default.
-- Safe [identity linking](/user-management/identity-linking) and merging of duplicate accounts. This protects against spoofing and reduces the user support burden.
-- Identity Provider (IdP) differences are normalized, so that you get consistency across user profiles. This reduces the likelihood of security issues related to differing semantics across providers.
-- Automatic bot detection and blocking, to protect against brute force attacks.
-- [Multi-Factor Authentication (MFA)](/user-management/mfa) available per environment to further enhance your app’s security posture.
-
-## Getting started
-
-Start integrating User Management into your app today, check out the [Quick Start](/user-management) guide to get started with AuthKit or review the [API Reference](/reference/user-management) material.

package/.docs/organized/docs/user-management/roles-and-permissions.mdx

@@ -1,155 +0,0 @@
----
-title: Roles and Permissions
-description: Manage and assign roles and permissions to users.
-showNextPage: true
-originalPath: >-
-  .tmp-workos-clone/packages/docs/content/user-management/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](/user-management/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/).
-
-![Roles section WorkOS Dashboard](https://images.workoscdn.com/images/946f05f6-e25c-45ae-96f0-fb6734c18411.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 included as part of session cookies in the [session JWT claims](/user-management/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/0ee8e707-0dd3-43ca-8504-8bf86fd2fb4e.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](/user-management/roles-and-permissions/organization-roles) section.
-
-### Assign roles
-
-Organization memberships require a role. Every user with an organization membership is automatically assigned the default role when added to an organization. This role can be edited.
-
-<DirectorySyncDiagram.Roles />
-
-You can retrieve the role slug from the user's [organization membership object](/reference/user-management/organization-membership) to determine their access level and capabilities within your application.
-
-### Delete roles
-
-When roles are deleted, all organization memberships are reassigned to the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all 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.
-
-### Role Assignment 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 _Roles and Permissions_ 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/157af155-1cd5-4714-9a4e-f56dd0005e36.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](/user-management/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.
-
-When switching from one role assignment source to another, refer to the [section below](/user-management/roles-and-permissions/role-assignment/migrating-role-assignment-source).
-
-## Role-aware sessions
-
-When a user signs into your app, a [user session](/user-management/sessions) is initiated. The authentication response includes an access token, a JSON Web Token (JWT), with the `role` claim indicating the user organization membership's role for that session.
-
-## Role assignment
-
-You can map identity provider groups to roles to automatically assign roles to users. AuthKit supports two methods for role assignment:
-
-### SCIM
-
-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](/user-management/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/user-management/organization-membership) and reflected in the [user’s session](/user-management/sessions/integrating-sessions/access-token).
-
-> Ensure [SSO JIT provisioning](/user-management/jit-provisioning/sso-jit-provisioning) is enabled for each organization using SSO role assignment.
-
-### 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](/user-management/roles-and-permissions/configure-roles-and-permissions/role-assignment-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.
-
-## 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.
-
-![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. 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](/user-management/roles-and-permissions/configure-roles-and-permissions/default-role) and [priority order](/user-management/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](/user-management/roles-and-permissions/role-assignment), [sessions](/user-management/roles-and-permissions/role-aware-sessions), and the [organization membership API](/reference/user-management/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/users-organizations.mdx

@@ -1,91 +0,0 @@
----
-title: Users and Organizations
-description: Flexible application modeling with user and membership features.
-showNextPage: true
-originalPath: >-
-  .tmp-workos-clone/packages/docs/content/user-management/users-organizations.mdx
----
-
-## Users
-
-The [User object](/reference/user-management/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](/user-management/email-password) or [OAuth](/user-management/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](/user-management/identity-linking) automatically.
-
-### Email verification
-
-All users will go through an initial [email verification process](/user-management/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, they will [automatically be considered verified](/user-management/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 User Management 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](/user-management/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](/user-management/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/user-management/organization-membership/deactivate) sets its status to `inactive` and revokes all active [sessions](/user-management/sessions). Note `pending` memberships cannot be deactivated and should be deleted using the [deleting membership API](/reference/user-management/organization-membership/delete) instead.
-- [Reactivating an organization membership](/reference/user-management/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/user-management/organization-membership/update). Note `pending` memberships cannot be reactivated. For this the user should go through the [invitation acceptance flow](/user-management/invitations) instead. If invitations are not needed, the organization membership can be [created as active directly](/reference/user-management/organization-membership/create).
-
-If your application uses a hard-delete model, you may use organization memberships without deactivation/reactivation by [deleting memberships](/reference/user-management/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/user-management/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](/user-management/jit-provisioning) into an organization if their email address matches one of the organization's [verified domains](/user-management/domain-verification). This allows customers to quickly onboard teammates.
-
-Users can also [invite individuals to organizations](/user-management/invitations), regardless of their email domain. This is handy for contractors within a company, or a collection of people without a shared domain.