@workos/mcp-docs-server 0.1.0

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

@@ -0,0 +1,78 @@
+---
+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/domain-verification.mdx

@@ -0,0 +1,28 @@
+---
+title: Domain Verification
+description: Verify organization domains for secure authentication and provisioning.
+showNextPage: true
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/user-management/domain-verification.mdx
+---
+
+## Introduction
+
+Domain verification allows IT admins to prove they control specific domains. This allows WorkOS to trust actions from users with the verified domain and enables authentication and membership policy enforcement for those users.
+
+Verifying an organization domain enables the following features:
+
+1. Users with the verified domain who sign in with the organization’s SSO connection don't need to [verify their email](/user-management/email-verification).
+2. By default, users with the verified domain are managed by the organization's [domain policy](/user-management/organization-policies/domain-policy), allowing for enhanced control over authentication and membership.
+
+## Self-serve domain verification
+
+Domain verification can be delegated to the [Admin Portal domain verification flow](/domain-verification). This out-of-the-box UI guides the IT admin to add a DNS TXT record to prove domain ownership. Once the DNS TXT record is correctly added, the organization domain is automatically verified.
+
+## Manual domain verification
+
+Verified domains may also be added manually via the [WorkOS Dashboard](https://dashboard.workos.com) or [API](/reference/organization/update). This shortcut is useful if the IT admin has already proven domain ownership in another context.
+
+> Manually verified domains can be used to define a domain policy that applies to any users with email addresses on that domain. The organization that defines this [domain policy](/user-management/organization-policies/domain-policy) exerts authentication policy control over that domain across your application. For this reason, it is important to verify ownership of manually added domains. Additionally, WorkOS does not allow addition of common consumer domains, like `gmail.com`.
+
+![Adding a verified domain in the dashboard](https://images.workoscdn.com/images/6686305b-3f3f-4c7e-8b39-90ca4958a5e3.png?auto=format&fit=clip&q=50)

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

@@ -0,0 +1,42 @@
+---
+title: Email + Password
+description: Configuring email and password authentication and requirements.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/email-password.mdx
+---
+
+## Introduction
+
+Email + Password authentication allows users to sign up and sign in to your application using an email address and password combination. This is one of the most common forms of authentication and is enabled by default.
+
+## Password configuration
+
+In the majority of cases, no additional configuration is required. However, depending on your application's security requirements you may wish to modify the password strength policy.
+
+### Modifying the password strength policy
+
+A strong set of password rules are applied to all users by default. This ensures that:
+
+- All passwords meet a minimum required length
+- Low complexity passwords are rejected
+- Breached passwords (flagged by [haveibeenpwned](https://haveibeenpwned.com)) are rejected
+
+These defaults are recommended in the majority of cases, however, if you wish to modify the password policy you can do so in the _Authentication_ section of the [WorkOS dashboard](https://dashboard.workos.com).
+
+You can enable password history to prevent password reuse. When modifying your policy, you can reject up to 10 of each user’s most recently used previous passwords. Password history is disabled by default.
+
+AuthKit will enforce your policy within the sign up and password reset flows.
+
+![Dashboard password strength policy](https://images.workoscdn.com/images/d9ab3375-78b8-4dc4-a15c-76af2fad671e.png?auto=format&fit=clip&q=80)
+
+### Disabling Email + Password
+
+Disabling this method entirely will prevent users from signing up or signing in using a password. This is useful when you want to restrict access to your application to only those users who have been provisioned via SSO.
+
+---
+
+## 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).
+
+Examples of building custom UI are also [available on GitHub](https://github.com/workos/authkit).

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

@@ -0,0 +1,29 @@
+---
+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

@@ -0,0 +1,46 @@
+---
+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/example-apps.mdx

@@ -0,0 +1,39 @@
+---
+title: Example apps
+description: View sample User Management apps.
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/example-apps.mdx
+---
+
+You can view minimal example apps that demonstrate how to use WorkOS User Management and AuthKit to authenticate users:
+
+<ExampleApps.Root>
+  <ExampleApps.Card href="https://github.com/workos/authkit" title="AuthKit" />
+  <ExampleApps.Card
+    href="https://github.com/workos/next-authkit-example"
+    title="Next.js AuthKit app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/remix-authkit-example"
+    title="Remix AuthKit app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/react-authkit-example"
+    title="React AuthKit app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/php-authkit-example"
+    title="PHP AuthKit app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/ruby-authkit-example"
+    title="Ruby AuthKit app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/python-authkit-example"
+    title="Python AuthKit app"
+  />
+  <ExampleApps.Card
+    href="https://github.com/workos/java-example-applications/tree/main/java-usermanagement-example"
+    title="Java AuthKit app"
+  />
+</ExampleApps.Root>

package/.docs/organized/docs/user-management/identity-linking.mdx

@@ -0,0 +1,52 @@
+---
+title: Identity Linking
+description: Automatic deduplication of user credentials across identity providers.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/identity-linking.mdx
+---
+
+## Introduction
+
+Users have unique email addresses, because each user’s access to their inbox represents ultimate access to all of their credentials and thus services they control. The [User object](/reference/user-management/user) unifies all of the identities they use so that your application does not have to consider different identity systems.
+
+Identity linking is the process in which WorkOS safely deduplicates various credentials across identity providers to offer a single, unified user interface. It does this by using the **email address** as the unique identifier and access to the email inbox as the source of truth.
+
+<UserManagementDiagrams.IdentityLinking />
+
+## Credentials
+
+A credential is an authentication method in a specific identity provider. For example, WorkOS offers a [password credential](/user-management/email-password) for users to authenticate with. In this case, WorkOS is the identity provider and password is the authentication method.
+
+[Google OAuth](/user-management/social-login) is another credential, where Google is the identity provider and OAuth is the authentication method.
+
+Users may use multiple types of authentication methods based on preference, perhaps because one is more convenient to use on one of their devices, or they simply didn’t remember which method they used in the past.
+
+## Email verification
+
+WorkOS ensures all user emails are unique via an [email verification process](/user-management/email-verification). By default, email verification is required by all users for authentication to succeed. This ensures that verified users are always returned to your application.
+
+When a user signs in with a new credential for the first time, e.g. they sign in through Google OAuth despite already having a password account, WorkOS will safely attach the new credential to the existing user. This is only performed if WorkOS can verify that the user has access to the email inbox referenced by that credential.
+
+WorkOS considers it a **security risk if the user cannot verify access to their email**. Some identity providers allow creating accounts with any email address. For instance, an IT admin of an organization with the domain `apple.com` could make an account for `billg@microsoft.com`. If access to `billg@microsoft.com` is not verified, the admin could sign in to the application as that user.
+
+> WorkOS does not complete the authentication flow when a new identity cannot be safely linked to an existing user to ensure account takeover risks are minimized.
+
+## Domain verification
+
+When an IT admin [verifies a domain for their organization](/user-management/domain-verification), it means they have access to create email inboxes. Thus, a **verified domain implies the ability to verify all users with that email domain**.
+
+In practice, when a domain is verified and an SSO connection is configured, users who sign in through an organization’s IdP are automatically considered email verified if the domain matches. This shortcut reduces friction for your end users.
+
+> Users who sign-in through SSO with an email address that is not a verified domain are not considered verified and will have go through the [email verification](/user-management/email-verification) process.
+
+## SSO identity linking
+
+Not only can a user have multiple credentials, they may also have multiple SSO credentials. This might happen when a user works with multiple organizations that require SSO authentication for all members. In this case, there is still only one [User object](/reference/user-management/user), but they would choose which organization’s SSO IdP to use when authenticating.
+
+![Example UI showing organization selection](https://images.workoscdn.com/images/876aeb05-cd96-46b4-9adf-3e9dd0208e47.png?auto=format&fit=clip&q=80)
+
+The email verification safety still applies. When the user signs-in for the first time through an SSO IdP where the user’s email address is not a verified domain, the user is asked to verify their email before the SSO credential is linked to their account.
+
+Users without a verified domain **must be invited to the organization** before they have access via SSO for the first time.
+
+> An [invitation](/user-management/invitations) ensures that the authentication flow gives the user an opportunity to go to the SSO’s identity provider.

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

@@ -0,0 +1,82 @@
+---
+title: Impersonation
+description: Learn how to sign into your application as one of your users.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/impersonation.mdx
+---
+
+## Introduction
+
+Impersonation allows administrators and support team members to assume the identity of any of your users, allowing them to reproduce or debug issues the user may be having in your application. The ability to see the application in an identical state as the user helps to greatly speed up the support process.
+
+## Enabling impersonation
+
+Since impersonation allows any member of your WorkOS team to bypass the normal authentication flow for a user, it is not enabled by default in any of your environments. You must have the **Admin** role in order to enable impersonation for an environment.
+
+![A screenshot showing the WorkOS Dashboard configuration card for impersonation](https://images.workoscdn.com/images/bf2d2b47-1dbb-4dd2-a0e9-4d27192b6353.png?auto=format&fit=clip&q=80)
+
+Navigate to _Authentication_ → _User Impersonation_ and select _Configure_ to enable impersonation for your current environment.
+
+## Using impersonation
+
+To impersonate one of your users, navigate to _Users_, select the user you'd like to impersonate, and under _Danger Zone_ select _Impersonate User_.
+
+![A screenshot of the User details page in the WorkOS Dashboard](https://images.workoscdn.com/images/afcfc2b9-275c-4a08-9976-ab9b1b30a7b8.png?auto=format&fit=clip&q=80)
+
+You will be prompted for the reason your are impersonating the user. It is optional to provide a reason in staging environments, and required in production. The reason will be recorded internally on the `session.created` event that is emitted whenever impersonation is used.
+
+If the user is a member of more than one organization, you will also need to choose which of
+these organizations you will be signing-into as the user. You can read more about users and organizations in our [dedicated guide](/user-management/users-organizations).
+
+Finally, click _Impersonate user_ to start an impersonation session, redirecting your browser to your application's callback endpoint with an authorization code for the impersonated user. You can read more about how to implement a callback endpoint in our [Quick Start guide](/user-management/2-add-authkit-to-your-app/add-a-callback-endpoint).
+
+> Impersonation sessions automatically expire after 60 minutes.
+
+Be aware that impersonating a user usually generally gives the same level of access as that user, allowing the impersonator to see the user's information. If your application contains sensitive user data, see the [Integrating impersonation](/user-management/impersonation/integrating-impersonation) section about how to customize your application when using impersonation.
+
+### Deep-linking to the impersonation flow
+
+You can deep-link to the impersonation flow in the WorkOS Dashboard from your own admin tool using the following URL structure:
+
+`https://dashboard.workos.com/<environment_id>/users/<user_id>?dialog=impersonate`
+
+## Auditing impersonation usage
+
+User sessions that were initiated via impersonation will be clearly marked as such when viewing their details in the WorkOS Dashboard. Additionally, WorkOS emits a [`session.created`](/events/session) event which you can view under the events for the user, or listen for in your application via the [events API](/events).
+
+![A screenshot of the User events page in the WorkOS Dashboard](https://images.workoscdn.com/images/e213fa51-4aa6-4260-8c31-84823fbcc77b.png?auto=format&fit=clip&q=80)
+
+The `session.created` event has an `impersonator` field that contains information about the impersonation session, like the `email` of your team member who performed the impersonation, along with their `reason` for doing so.
+
+## Integrating impersonation
+
+No additional code is required to start using impersonation once you have integrated with WorkOS. However, many developers may want to augment their application's behavior when your team members are impersonating one of your users.
+
+The response from the [Authenticate with Code API](/reference/user-management/authentication/code) will include an additional `impersonator` field when the resulting session was created via impersonation, containing the impersonator's `email` and `reason` for using impersonation. Similarly, the `access_token` will include an `act` claim with the impersonator's `email`. Your application can use either in order to trigger impersonation-specific behavior.
+
+A common enhancement is to change the appearance of the application in order to make it obvious to the viewer they are currently impersonating one of your users, such as a "Staff Bar" displayed at the top of the viewport. You may also want to restrict access to sensitive views or redact certain fields in your application.
+
+### Impersonation with `authkit-nextjs`
+
+If using the [`authkit-nextjs` library](https://github.com/workos/authkit-nextjs), impersonation can be easily added by using the provided helper component.
+
+After completing the setup instructions in the [quick start](/user-management) guide, add the Impersonation component to your app code.
+
+```js title="Impersonation component"
+import { Impersonation } from '@workos-inc/authkit-nextjs';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <Impersonation />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+The above will automatically render a visually distinct frame on your page with an option to hide it or stop the impersonation session.
+
+![A screenshot showing the Impersonation frame rendered over a page](https://images.workoscdn.com/images/c4305ab6-d4fa-4f36-be9c-5a60ee12a7b3.png?auto=format&fit=clip&q=80)