@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/authkit/connect/standalone.mdx

@@ -0,0 +1,179 @@
+---
+title: Standalone Connect
+description: Integrate Connect's OAuth API with your existing authentication stack.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/connect/standalone.mdx
+---
+
+## Overview
+
+Standalone Connect allows applications with existing authentication systems to use AuthKit as their OAuth authorization server. You maintain your existing authentication stack while leveraging AuthKit's OAuth infrastructure for token issuance and management.
+
+Unlike standard AuthKit integration, Standalone Connect delegates authentication to your application, then handles the OAuth flow and token issuance for OAuth clients. This feature works with [OAuth applications](/authkit/connect/oauth) only—[M2M applications](/authkit/connect/m2m) use the `client_credentials` flow which doesn't involve user authentication.
+
+## When to use Standalone Connect
+
+Use Standalone Connect when you:
+
+- Have an existing authentication stack in your application.
+- Need to enable OAuth-based integrations, like a [CLI](/authkit/cli-auth) app or [MCP](/authkit/mcp) server.
+- Want to support third-party applications accessing your users' resources.
+
+## Getting started
+
+### Create an OAuth application
+
+Before testing your Standalone Connect integration, you'll need to [create an OAuth application](/authkit/connect/oauth) in the WorkOS Dashboard. If you need to support MCP auth, you'll need to enable Client ID Metadata Document (CIMD), which you can read more about in the [MCP guide](/authkit/mcp).
+
+### Configure your Login URI
+
+Navigate to _Connect_ → _Configuration_ in the [WorkOS Dashboard](https://dashboard.workos.com) and provide your **Login URI**.
+
+The **Login URI** is where AuthKit will redirect users to authenticate with your existing system. You can only configure one Login URI per environment.
+
+Your Login URI must:
+
+- Use HTTPS in production.
+- Accept an `external_auth_id` query parameter.
+- Authenticate users with your existing system.
+- Call the AuthKit completion API after successful authentication. More on that below.
+
+Example: `https://your-app.example.com/auth/login`
+
+## Authentication flow
+
+### (1) OAuth client initiates flow
+
+OAuth clients start the authorization flow with AuthKit following standard OAuth 2.0. This could be a third-party application, partner integration, or any OAuth-enabled client.
+
+### (2) AuthKit redirects to your application
+
+AuthKit redirects users to your Login URI with an `external_auth_id` parameter:
+
+```txt
+https://your-app.example.com/auth/login?external_auth_id=01J3X4Y5Z6A7B8C9D0E1F2G3H4
+```
+
+The `external_auth_id` is a temporary identifier used to complete the flow with AuthKit.
+
+### (3) Authenticate the user
+
+Your application authenticates users with your existing system. If users have an active session, skip to the next step.
+
+AuthKit handles OAuth consent separately, so your application doesn't need to display any consent screens.
+
+### (4) Complete authentication with AuthKit
+
+Call the [AuthKit completion API](/reference/workos-connect/standalone/complete) after authenticating the user, passing the `external_auth_id` that your Login URI originally received:
+
+```js
+const response = await fetch('https://api.workos.com/authkit/oauth2/complete', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${process.env.WORKOS_API_KEY}`,
+  },
+  body: JSON.stringify({
+    external_auth_id: externalAuthId,
+    user: {
+      id: user.id,
+      email: user.email,
+      first_name: user.firstName,
+      last_name: user.lastName,
+      metadata: { department: user.department },
+    },
+  }),
+});
+
+const { redirect_uri } = await response.json();
+```
+
+### (5) Return control to AuthKit
+
+Redirect users to the `redirect_uri` from the API response. AuthKit displays a consent screen if needed, issues tokens, and completes the OAuth flow.
+
+## Integrating via the API
+
+### Dynamic consent options
+
+You can provide `user_consent_options` to display options during the OAuth consent screen. This is useful when users need to choose specific resources or contexts (like a parent resource in your application) to grant access to.
+
+Each consent option must include:
+
+- `claim`: The name of the access token claim that will hold the user's selected value.
+- `type`: The format of the option. Only `enum` is supported currently.
+- `label`: Display text for the option.
+- `choices`: Array of choices (can be flat or grouped).
+
+```js
+const response = await fetch('https://api.workos.com/authkit/oauth2/complete', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${process.env.WORKOS_API_KEY}`,
+  },
+  body: JSON.stringify({
+    external_auth_id,
+    user: { id: user.id, email: user.email },
+    user_consent_options: [
+      {
+        claim: 'urn:example:tenant',
+        type: 'enum',
+        label: 'Environment',
+        choices: [
+          {
+            group: 'Production',
+            choices: [
+              { value: 'prod_us', label: 'US-East' },
+              { value: 'prod_eu', label: 'EU-West' },
+            ],
+          },
+          {
+            group: 'Development',
+            choices: [
+              { value: 'dev_main', label: 'Development' },
+              { value: 'staging', label: 'Staging' },
+            ],
+          },
+        ],
+      },
+    ],
+  }),
+});
+```
+
+The selected values appear as custom claims in the issued tokens. For example, if the user selects one of the above options, the token will include:
+
+```json
+{
+  "sub": "user_123",
+  "email": "user@example.com",
+  "urn:example:tenant": "prod_us"
+  // ...
+}
+```
+
+### Error handling
+
+If the `external_auth_id` is invalid, the call to the AuthKit completion API will fail. Your application is free to choose how to handle this case, but redirecting to your application's homepage is recommended.
+
+### Token verification
+
+Resource servers verify tokens issued by AuthKit using standard Connect token verification:
+
+```js
+import { jwtVerify, createRemoteJWKSet } from 'jose';
+
+const JWKS = createRemoteJWKSet(new URL('https://authkit_domain/oauth2/jwks'));
+
+async function verifyToken(token) {
+  const { payload } = await jwtVerify(token, JWKS, {
+    audience: 'client_123456789',
+    issuer: 'https://authkit_domain',
+  });
+
+  return payload;
+}
+```
+
+See the [Connect documentation](/authkit/connect/oauth/verifying-tokens) for details on token expiration, refresh tokens, and revocation.

package/.docs/organized/docs/authkit/connect.mdx

@@ -0,0 +1,65 @@
+---
+title: Connect
+description: Enable other applications to access your users and their identities.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/connect.mdx
+---
+
+## Introduction
+
+Connect is a set of controls and APIs that developers can use to allow different types of applications to access their 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.
+
+Unlike AuthKit's other features that help users sign into **your application**, Connect enables **other applications** to authenticate and access your users' data through secure, managed APIs.
+
+## Common use-cases
+
+**Customer applications**
+: Enable your customers to build custom integrations with your platform. This can include allowing them to add a "Sign in with [your app]" button on their login page.
+
+**Auxiliary applications**
+: Allow secondary applications that support your primary application, such as support tools or discussion forums, to authenticate using the same user identities in AuthKit.
+
+**Partner integrations**
+: Issue credentials for trusted partners to authenticate with when calling your application's API.
+
+## Getting started
+
+Each Connect integration is defined as an Application, which can be created inside of the WorkOS Dashboard.
+
+When creating an application, you first choose the type of integration: **OAuth** or Machine-to-Machine (**M2M**).
+
+### OAuth applications
+
+Select OAuth when building web or mobile applications where the actor being authenticated is a [User](/reference/authkit/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.
+
+[Learn more about OAuth applications →](/authkit/connect/oauth)
+
+### M2M applications
+
+Select M2M when the application will be a third-party service, such as one of your customer's applications. Integrating with an M2M application uses the underlying `client_credentials` flow.
+
+Unlike OAuth applications, the actor being authenticated is not an individual user. Instead issued access tokens will contain an `org_id` claim which represents the customer you are granting access to via the M2M application.
+
+The M2M application will use its `client_id` and `client_secret` to authenticate requests to your application's API or services.
+
+[Learn more about M2M applications →](/authkit/connect/m2m)
+
+## Concepts
+
+All Connect applications share the following concepts:
+
+### Participants
+
+When using Connect, there are several actors involved with the integration of each Application:
+
+- **Relying Party**: The application that receives Connect-issued tokens and identity information. It may also use the access token to make requests to your API.
+- **Resource server**: The service (generally your app) that allows other clients to authenticate using the Connect-issued tokens.
+- **Authorization server**: This is Connect, the issuer of identity and access tokens to requesting clients after authenticating the user.
+
+### 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 [Connect APIs](/reference/workos-connect).
+
+When sharing app credentials with an external party, use a secure method — like encrypted email or file sharing — and make sure the recipient is properly authenticated.

package/.docs/organized/docs/authkit/custom-email-providers.mdx

@@ -0,0 +1,141 @@
+---
+title: Custom Email Providers
+description: Learn how to send emails through your own email service provider.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/custom-email-providers.mdx
+---
+
+## Introduction
+
+By default, WorkOS will send emails via our default email service provider, either through our domain or through your own [custom email domain](/custom-domains/email). If you would like to have more control over deliverability, reputation, and compliance, while still offloading the heavy lifting of email handling, you can configure a custom email provider. This option is also ideal if you already have an existing email service provider configuration.
+
+---
+
+## Configure a custom email provider
+
+To configure a custom email provider for an environment, navigate to [_Emails_ → _Providers_](https://dashboard.workos.com/environment/emails/providers) and click _Enable_ next to the provider you would like to use and enter the required information.
+
+> If the email service provider you'd like to use is not listed, please [contact support](mailto:support@workos.com).
+
+![A screenshot showing the WorkOS Dashboard email providers page](https://images.workoscdn.com/images/660bd317-6240-40ce-8cb7-d80dccac294a.png?auto=format&fit=clip&q=80)
+
+### Amazon SES
+
+To connect WorkOS to Amazon SES, you'll need to [create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) with an access key, and [verify email sending identities](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html). Ensure the IAM user has a policy like the following:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "SendEmailAccess",
+      "Effect": "Allow",
+      "Action": "ses:SendEmail",
+      "Resource": [
+        "arn:aws:ses:<region>:<accountId>:identity/*",
+        "arn:aws:ses:<region>:<accountId>:configuration-set/*"
+      ]
+    },
+    {
+      "Sid": "IdentityManagementAccess",
+      "Effect": "Allow",
+      "Action": ["ses:GetIdentityVerificationAttributes", "ses:ListIdentities"],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+You'll need to update the resource scope with your Amazon SES region and account ID. For additional ways to restrict access, refer to the [Amazon SES documentation](https://docs.aws.amazon.com/ses/latest/dg/control-user-access.html).
+
+> If you're interested in using temporary security credentials to access Amazon SES, please [contact support](mailto:support@workos.com).
+
+Once you have an IAM user with the necessary permissions and have verified sending identities, you can configure the Amazon SES custom email provider in the [WorkOS Dashboard](https://dashboard.workos.com/):
+
+![A screenshot showing the WorkOS Dashboard Amazon SES custom email provider configuration](https://images.workoscdn.com/images/4df55e43-d68c-410c-9452-32978e0ca874.png?auto=format&fit=clip&q=50)
+
+### Mailgun
+
+Before configuring the Mailgun custom email provider in WorkOS, you'll need to [verify your domain in your Mailgun account](https://help.mailgun.com/hc/en-us/articles/32884700912923-Domain-Verification-Setup-Guide).
+
+Once you've verified a domain, you'll need an API key, which you can create on the [API Security page of the Mailgun dashboard](https://app.mailgun.com/settings/api_security). The API key is used to validate verified domains in your account and send emails.
+
+![A screenshot showing the Mailgun API Security page](https://images.workoscdn.com/images/fc6d06dd-790e-419e-ba0d-5a1783e8748d.png?auto=format&fit=clip&q=80)
+
+Once you've verified your domain and obtained an API key, you can configure the Mailgun custom email provider in the [WorkOS Dashboard](https://dashboard.workos.com/):
+
+![A screenshot showing the Mailgun custom email provider configuration](https://images.workoscdn.com/images/5e287a26-7851-49f5-95b5-bc74ab58b506.png?auto=format&fit=clip&q=80)
+
+### Postmark
+
+Before configuring the Postmark custom email provider in WorkOS, you'll need to [verify sender signatures in your Postmark account](https://postmarkapp.com/developer/user-guide/managing-your-account/managing-sender-signatures).
+
+Once you've verified a sender signature, you'll need an account and server token, which you can find on the [API Tokens page of the Postmark dashboard](https://postmarkapp.com/account/api-tokens).
+
+![A screenshot showing the Postmark API Tokens page](https://images.workoscdn.com/images/e441ca41-2768-4887-83f1-8f298ab25847.png?auto=format&fit=clip&q=50)
+
+The account token is used to validate sender signatures in your account, and the server token is used to send emails.
+
+Once you've verified your sender signature and obtained your account and server token, you can configure the Postmark custom email provider in the [WorkOS Dashboard](https://dashboard.workos.com/):
+
+![A screenshot showing the Postmark custom email provider configuration](https://images.workoscdn.com/images/21f94d07-b661-4a24-9e2b-940cd0bbfdaa.png?auto=format&fit=clip&q=50)
+
+Upon enabling the Postmark custom email provider, a WorkOS transactional message stream with the ID `workos-transactional-s` will be created for you. All WorkOS emails will be sent using this message stream.
+
+### Resend
+
+Before configuring the Resend custom email provider in WorkOS, you'll need to [verify domains in your Resend account](https://resend.com/docs/dashboard/domains/introduction).
+
+Once you've verified your domain, you'll need to create an API key with the "Full access" permission on the [Resend API Keys page](https://resend.com/api-keys).
+
+![A screenshot showing creating an API key in the Resend dashboard](https://images.workoscdn.com/images/ce0ae76c-7ab4-4506-9e48-78a61243a42d.png?auto=format&fit=clip&q=50)
+
+"Full access" permission is required to fetch verified domains and send emails.
+
+Once you've verified your domain and obtained an API key, you can configure the Resend custom email provider in the [WorkOS Dashboard](https://dashboard.workos.com/):
+
+![A screenshot showing the Resend custom email provider configuration](https://images.workoscdn.com/images/25efadf6-405f-416b-aaa0-7e7fb266034a.png?auto=format&fit=clip&q=50)
+
+### SendGrid
+
+Before configuring the SendGrid custom email provider in WorkOS, you'll need to verify your domain in the [Sender Authentication settings in your SendGrid dashboard](https://app.sendgrid.com/settings/sender_auth).
+
+Once you've verified your domain, you'll need to create an API key under _Settings_ → _API Keys_ in the [SendGrid dashboard](https://app.sendgrid.com/settings/api_keys).
+
+![A screenshot showing the SendGrid API Keys side panel](https://images.workoscdn.com/images/61bf31b4-0e7f-4616-988f-69319d542866.png?auto=format&fit=clip&q=50)
+
+For API key permissions, select "Full Access" for Mail Send, and "Read Access" for Sender Authentication.
+
+Once you've verified your domain and obtained an API key, you can configure the SendGrid custom email provider in the [WorkOS Dashboard](https://dashboard.workos.com/):
+
+![A screenshot showing the SendGrid custom email provider configuration](https://images.workoscdn.com/images/4502c8ad-2bdf-481b-82a7-0d8829032da4.png?auto=format&fit=clip&q=50)
+
+---
+
+## Re-enable the WorkOS default provider
+
+At any time when you are using a custom email provider, you can re-enable the WorkOS default provider by navigating to [_Emails_ → _Providers_](https://dashboard.workos.com/environment/emails/providers) and clicking _Enable_ next to the WorkOS provider.
+
+![A screenshot showing re-enabling the WorkOS default provider](https://images.workoscdn.com/images/7b4f4713-3381-49aa-b77c-679c9698b429.png?auto=format&fit=clip&q=80)
+
+Alternatively, you can also remove your current custom email provider, which will automatically re-enable the WorkOS default provider.
+
+![A screenshot showing removing a custom email provider](https://images.workoscdn.com/images/7b4f4713-3381-49aa-b77c-679c9698b429.png?auto=format&fit=clip&q=80)
+
+---
+
+## Frequently asked questions
+
+### What types of emails are sent through custom email providers?
+
+All transactional emails for your users will be sent through your custom email provider when configured. This includes AuthKit invitations and magic codes, Radar challenges, and Admin Portal notification emails.
+
+### If I am using a custom email provider, do I need to set up a custom email domain in WorkOS?
+
+No. When using a custom email provider, you configure the sending domain in that provider, not in WorkOS. Any custom email domain set up in WorkOS will not be used.
+
+### What happens if emails fail to send via my custom email provider?
+
+If emails fail to send via your custom email provider, you will be notified according to your notifications preferences via the [WorkOS Dashboard](https://dashboard.workos.com/), email, or Slack. You can also utilize the [_Emails_ → _Events_ page](https://dashboard.workos.com/environment/emails/events) in the WorkOS Dashboard to track email delivery failures.
+
+Additionally, repeated delivery failures may cause the provider to suppress the recipient's email address. See [Check suppression status](/email/e-check-suppression-status) for how to check and resolve suppressions.

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

@@ -2,12 +2,12 @@
 title: Custom Emails
 description: Learn how to send your own emails for user lifecycle events.
 showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/custom-emails.mdx
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/custom-emails.mdx
 ---
 
 ## Introduction
 
-By default, WorkOS will send emails related to User Management for you, such as password reset and Magic Auth. If you’d like to customize email content or have more control over deliverability, you can turn off the default emails and deliver your own.
+By default, WorkOS will send emails related to AuthKit for you, such as password reset and Magic Auth. If you'd like to customize email content or have more control over deliverability, you can turn off the default emails and deliver your own emails using the WorkOS API.
 
 ---
 
@@ -28,17 +28,17 @@ Once you've turned off the default user invitation emails, use the information b
 **[invitation.created](/events/invitation)**
 : Event emitted when an invitation is created, which can be consumed using the events API or webhooks.
 
-**[Get Invitation API](/reference/user-management/invitation/get)**
+**[Get Invitation API](/reference/authkit/invitation/get)**
 : Used to retrieve the invitation object from the ID in the invitation created event.
 
-**[Send Invitation API](/reference/user-management/invitation/send)**
+**[Send Invitation API](/reference/authkit/invitation/send)**
 : Used to create an invitation via the API without handling the invitation created event.
 
 ### Set up your user invitation URL {{ "visibility": "no-quick-nav" }}
 
-Make sure you have the correct user invitation URL set on your _Redirects_ page. The default setting is the AuthKit URL for accepting invitations. If you are using your own authentication UI, make sure the URL path is configured on your end to capture the `invitation_token` query parameter, and [pass it into one of the authenticate methods](/reference/user-management/authentication/code).
+Make sure you have the correct user invitation URL set on your _Redirects_ page. The default setting is the AuthKit URL for accepting invitations. If you are using your own authentication UI, make sure the URL path is configured on your end to capture the `invitation_token` query parameter, and [pass it into one of the authenticate methods](/reference/authkit/authentication/code).
 
-![A screenshot showing the WorkOS Dashboard configuration card for user invitation URL](https://images.workoscdn.com/images/5e7f404e-5b47-48e3-a346-9ac689ced400.png?auto=format&fit=clip&q=50)
+![A screenshot showing the WorkOS Dashboard configuration card for user invitation URL](https://images.workoscdn.com/images/540542e4-8fd8-4a0f-8715-b5ae1715d46e.png?auto=format&fit=clip&q=50)
 
 ### (A) Handle manually creating invitations {{ "visibility": "no-quick-nav" }}
 
@@ -71,10 +71,10 @@ Once you've turned off the default Magic Auth emails, use the information below
 **[magic_auth.created](/events/magic-auth)**
 : Event emitted when a user initiates a Magic Auth authentication, which can be consumed using the events API or webhooks.
 
-**[Get Magic Auth API](/reference/user-management/magic-auth/get)**
+**[Get Magic Auth API](/reference/authkit/magic-auth/get)**
 : Used to retrieve the Magic Auth object from the ID in the Magic Auth created event.
 
-**[Create Magic Auth API](/reference/user-management/magic-auth/create)**
+**[Create Magic Auth API](/reference/authkit/magic-auth/create)**
 : Used to create a Magic Auth code via the API without handling the Magic Auth created event.
 
 ### (A) Handle Magic Auth codes created via AuthKit {{ "visibility": "no-quick-nav" }}
@@ -102,10 +102,10 @@ Once you've turned off the default email verification emails, use the informatio
 **[email_verification.created](/events/email-verification)**
 : Event emitted when a user requires email verification, which can be consumed using the events API or webhooks.
 
-**[Get Email Verification API](/reference/user-management/email-verification/get)**
+**[Get Email Verification API](/reference/authkit/email-verification/get)**
 : Used to retrieve the email verification object from the ID in the email verification created event.
 
-**[Email Verification Required error](/reference/user-management/authentication-errors/email-verification-required-error)**
+**[Email Verification Required error](/reference/authkit/authentication-errors/email-verification-required-error)**
 : Returned in the API when attempting to authenticate a user that requires email verification.
 
 ### (A) Handle email verification codes created via AuthKit {{ "visibility": "no-quick-nav" }}
@@ -118,7 +118,7 @@ You can skip this step if you're building your own authentication app.
 
 ### (B) Handle email verification codes created via the API {{ "visibility": "no-quick-nav" }}
 
-If you are using the [authentication API](/reference/user-management/authentication), an `email_verification_required` error will be returned if the user you're authenticating needs to verify their email. This error contains an `email_verification_id` that can be used to call the Get Email Verification API endpoint which returns the email verification object that contains the information needed to send the email.
+If you are using the [authentication API](/reference/authkit/authentication), an `email_verification_required` error will be returned if the user you're authenticating needs to verify their email. This error contains an `email_verification_id` that can be used to call the Get Email Verification API endpoint which returns the email verification object that contains the information needed to send the email.
 
 ### Send your email {{ "visibility": "no-quick-nav" }}
 
@@ -133,17 +133,17 @@ Once you've turned off the default password reset emails, use the information be
 **[password_reset.created](/events/password-reset)**
 : Event emitted when a user requests to reset their password, which can be consumed using the events API or webhooks.
 
-**[Get Password Reset API](/reference/user-management/password-reset/get)**
+**[Get Password Reset API](/reference/authkit/password-reset/get)**
 : Used to retrieve the password reset object from the ID in the password reset created event.
 
-**[Create Password Reset API](/reference/user-management/password-reset/create)**
+**[Create Password Reset API](/reference/authkit/password-reset/create)**
 : Used to create a password reset object via the API without handling the password reset created event.
 
 ### Set up your password reset URL {{ "visibility": "no-quick-nav" }}
 
-Make sure you have the correct password reset URL set on your _Redirects_ page. The default setting is the AuthKit URL for resetting passwords. If you are using your own authentication UI, make sure the URL path is configured on your end to capture the `token` query parameter, and [use it to reset the password](/reference/user-management/password-reset/reset-password).
+Make sure you have the correct password reset URL set on your _Redirects_ page. The default setting is the AuthKit URL for resetting passwords. If you are using your own authentication UI, make sure the URL path is configured on your end to capture the `token` query parameter, and [use it to reset the password](/reference/authkit/password-reset/reset-password).
 
-![A screenshot showing the WorkOS Dashboard configuration card for password reset URL](https://images.workoscdn.com/images/d075a76b-4c87-4e82-8f09-2028f460ac26.png?auto=format&fit=clip&q=50)
+![A screenshot showing the WorkOS Dashboard configuration card for password reset URL](https://images.workoscdn.com/images/2b6abd95-459b-4f33-aab5-8217f412aed2.png?auto=format&fit=clip&q=50)
 
 ### (A) Handle password resets created via AuthKit {{ "visibility": "no-quick-nav" }}
 

package/.docs/organized/docs/authkit/directory-provisioning.mdx

@@ -0,0 +1,89 @@
+---
+title: Directory Provisioning
+description: Manage users and organization memberships via directory sync providers.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/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
+
+Directory provisioning is supported for all SCIM directory providers, Google Workspace, and SFTP.
+
+## 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](/authkit/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](/authkit/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 AuthKit.
+
+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/authkit/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/authkit/organization-membership) will be set to `active`.
+
+## Custom attributes
+
+When using directory provisioning, [custom attributes](/directory-sync/attributes) configured on directory users are available on the corresponding organization membership. This allows you to access IdP-sourced attributes like department, job title, and cost center directly from the [membership object](/reference/authkit/organization-membership) or in [JWT templates](/authkit/jwt-templates).
+
+When a directory user's attributes are updated, the changes are automatically reflected on the linked organization membership's `custom_attributes`.
+
+> If the membership is also linked to an [SSO Profile](/reference/sso/profile), the directory user's custom attributes take precedence.
+
+## Directory provisioning actions
+
+Below is a list of directory provisioning and deprovisioning actions and the corresponding changes triggered in AuthKit. If you're using standalone Directory Sync, refer to the [standalone Directory Sync documentation](/directory-sync/api-overview/directory).
+
+Actions depend on the user's email domain:
+
+- A user is domain-managed when their email domain matches one of the [organization's verified domains](/reference/domain-verification). These users are fully managed by the directory.
+- A user is a domain guest when their email domain does not match one of the [organization's verified domains](/reference/domain-verification). Changes only impact the linked organization membership.
+
+| Directory Action                                     | Changes triggered in WorkOS                                                                                                                                                                                                                                        | Event(s) Emitted                                                                                 |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| Directory user provisioned                           | [User](/reference/authkit/user) and [organization membership](/reference/authkit/organization-membership) objects created. Domain-managed users are created with an active status, while domain guest users are invited to the organization with a pending status. | [user.created](/events/user), [organization_membership.created](/events/organization-membership) |
+| Directory user info updated                          | For domain-managed users, any updates to the user's name will be reflected on the [user](/reference/authkit/user) object. Otherwise, the user object will not be modified. User email address is always immutable.                                                 | [user.updated](/events/user), [organization_membership.updated](/events/organization-membership) |
+| Directory user with active membership 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 with pending membership deprovisioned | Organization membership deleted.                                                                                                                                                                                                                                   | [organization_membership.deleted](/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 AuthKit. Why would a directory user not be provisioned in AuthKit?
+
+Directory users need to have a primary email address to be provisioned in AuthKit. 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 AuthKit, as emails are unique to AuthKit 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/authkit/user) is immutable, but the email on the underlying [directory user](/reference/directory-sync/directory-user) object will be modified.
+
+### Why is there a distinction between domain-managed users and domain guest users?
+
+For domain-managed users, the organization has proven they own the email domain through [domain verification](/authkit/domain-verification), and therefore have full control over the user's account and email. This allows the directory to manage all aspects of the [user object](/reference/authkit/user).
+
+For domain guests, the organization has not proven ownership of the user's email domain. As a result, the organization only has the ability to manage data within the scope of the organization itself, represented by the [organization membership object](/reference/authkit/organization-membership).
+
+### Why aren't organization memberships deactivated when a directory is deleted?
+
+User deprovisioning and directory deletion have different behaviors because they serve different use cases. Deactivating all users is typically an off-boarding task that affects the entire organization, not just the directory. By leaving memberships active when a directory is deleted, customers can switch directory providers without the disruption of deactivating all memberships.

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

@@ -2,8 +2,7 @@
 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
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/domain-verification.mdx
 ---
 
 ## Introduction
@@ -12,8 +11,8 @@ Domain verification allows IT admins to prove they control specific domains. Thi
 
 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.
+1. Users with the verified domain who sign in with the organization’s SSO connection don't need to [verify their email](/authkit/email-verification).
+2. By default, users with the verified domain are managed by the organization's [domain policy](/authkit/organization-policies/domain-policy), allowing for enhanced control over authentication and membership.
 
 ## Self-serve domain verification
 
@@ -23,6 +22,6 @@ Domain verification can be delegated to the [Admin Portal domain verification fl
 
 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`.
+> 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](/authkit/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)
+![Adding a verified domain in the dashboard](https://images.workoscdn.com/images/c015b42d-fc39-453c-a4c9-1be220c88a37.png?auto=format&fit=clip&q=80)

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

@@ -2,7 +2,7 @@
 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
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/email-password.mdx
 ---
 
 ## Introduction
@@ -37,6 +37,6 @@ Disabling this method entirely will prevent users from signing up or signing in
 
 ## 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).