@workos/mcp-docs-server 0.1.0

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

@@ -0,0 +1,169 @@
+---
+title: Actions
+description: Customize authentication flows with your own logic.
+showNextPage: true
+featureFlag: actions-docs
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/actions.mdx
+---
+
+## Introduction
+
+Actions allow you to change the behavior of various flows within the WorkOS platform including user registration and authentication using your own custom logic.
+
+When an action is configured for a particular request type, WorkOS synchronously calls the associated action endpoint and waits for a response that allows or denies the operation. When WorkOS calls an actions endpoint, the request includes contextual metadata such as the profile of the user performing the operation, the organization associated with the operation, or the IP address, all of which you can use for decisioning within the endpoint.
+
+### Action types
+
+WorkOS allows you to configure actions that execute during various user operations:
+
+- **Authentication**: Authentication actions run after a user completes Email + Password, Magic Auth authentication, SSO, or Social Login and before they are redirected to your application.
+- **User registration**: User registration actions run after a user attempts to register for your application using Email + Password, Magic Auth sign up, SSO, or Social Login and before they are provisioned.
+
+## Configuring actions
+
+To configure actions, you'll need to:
+
+- Host an actions endpoint that receive requests from WorkOS
+- Register your endpoints with WorkOS
+- Implement the custom logic of your endpoint
+- Test your endpoints
+
+## Set up your endpoint
+
+Create a public endpoint that WorkOS can make requests to. This endpoint should use HTTPS and should accept POST requests with the `workos-signature` header. This header is used for verifying the request's authenticity from WorkOS.
+
+<CodeBlock>
+  <CodeBlockTab language="js" file="actions-endpoint-next" title="Next.js" />
+  <CodeBlockTab language="js" file="actions-endpoint-express" title="Express" />
+</CodeBlock>
+
+> WorkOS sends the header as `WorkOS-Signature`, but many web servers normalize HTTP request headers to their lowercase variants.
+
+---
+
+## Register your endpoint
+
+Set the actions endpoint URL in the [WorkOS Dashboard](https://dashboard.workos.com/). Set _Enable action_ and choose **Save changes**.
+
+![WorkOS Dashboard Actions UI](https://images.workoscdn.com/images/84c8a62b-d8bc-4c46-8ccd-eda4c245645e.png?auto=format&fit=clip&q=80)
+
+### Choosing error handling behavior
+
+Each actions endpoint must specify its error handling behavior. By default, if there is an issue reaching your endpoint or validating the response, WorkOS will deny the operation. If this is not the desired behavior for your use case, you can choose a different behavior depending on the action endpoint type; for example, for authentication actions, you can choose _Allow authentication_.
+
+---
+
+## Implement your endpoint
+
+Upon receiving a request, you should respond with an `HTTP 200 OK` as well as a valid response body to signal to WorkOS that the request was successfully handled.
+
+### (A) Validate the requests using the SDK
+
+Before processing the request payload, verify the request was sent by WorkOS and not an unknown party.
+
+WorkOS includes a unique signature in each actions request that it sends, allowing you to verify the authenticity of the request. In order to verify this signature, you must obtain the secret that is generated for you when you set up your actions endpoint in the WorkOS dashboard. Ensure that this secret is stored securely on your actions endpoint server as an environment variable.
+
+The SDKs provide a method to validate the timestamp and signature of an actions. Examples using these methods are included below. The parameters are the payload (raw request body), the request header, and the actions secret.
+
+<CodeBlock title="Actions validation">
+  <CodeBlockTab language="js" file="actions-validation-next" title="Next.js" />
+  <CodeBlockTab
+    language="js"
+    file="actions-validation-express"
+    title="Express"
+  />
+</CodeBlock>
+
+There is an optional parameter, tolerance, that sets the time validation for the actions request in seconds. The SDK methods have default values for tolerance, usually 3–5 minutes.
+
+### (B) Validate the requests manually
+
+If implementing actions request validation yourself, you’ll need to use the following steps:
+
+First, extract the timestamp and signature from the header. There are two values to parse from the `WorkOS-Signature` header, delimited by a `,` character.
+
+| Key                | Value                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `issued_timestamp` | The number of milliseconds since the epoch time at which the event was issued, prefixed by `t=` |
+| `signature_hash`   | The HMAC SHA256 hashed signature for the request, prefixed by `v1=`                             |
+
+To avoid replay attacks, we suggest validating that the `issued_timestamp` does not differ too much from the current time.
+
+Next, construct the expected signature. The expected signature is computed from the concatenation of:
+
+1. `issued_timestamp`
+2. The `.` character
+3. The request’s body as a utf-8 decoded string
+
+Hash the string using HMAC SHA256, using the actions secret as the key. The expected signature will be the hex digest of the hash. Finally, compare signatures to make sure the actions request is valid.
+
+Once you’ve determined the event request is validly signed, it’s safe to use the event payload in your application’s business logic.
+
+### Create an IP allowlist
+
+WorkOS sends actions requests from a fixed set of IP addresses. It’s recommended to restrict access to your actions endpoint to only these IP addresses:
+
+```plain title="WorkOS IP addresses"
+3.217.146.166
+23.21.184.92
+34.204.154.149
+44.213.245.178
+44.215.236.82
+50.16.203.9
+52.1.251.34
+52.21.49.187
+174.129.36.47
+```
+
+---
+
+## Build the endpoint response
+
+The endpoint must respond with a signed JSON object indicating a `verdict` of `Allow` or `Deny` as well as an optional `error_message` in the event the `verdict` is `Deny`.
+
+Based on the payload data received, you can determine whether to allow or deny the operation. Each action type receives a different payload model, so be sure to handle the appropriate data in your handler.
+
+### (A) Respond using the SDK
+
+The SDK provides a method to create the signed response.
+
+<CodeBlock title="Actions response">
+  <CodeBlockTab language="js" file="actions-response-next" title="Next.js" />
+  <CodeBlockTab language="js" file="actions-response-express" title="Express" />
+</CodeBlock>
+
+### (B) Respond manually
+
+If implementing the construction of the actions response yourself, you’ll need to use the following steps:
+
+First, store the current epoch timestamp to a variable.
+
+Next, construct the JSON response. The JSON response must contain the following:
+
+- `timestamp`: The epoch timestamp you recorded
+- `verdict`: Indicates whether to allow or deny the action. Allowed values: `'Allow' | 'Deny' | 'allow' | 'deny'`
+- `error_message`: An optional, 500 character maximum string. This should only be provided with a `verdict` of `deny` or `Deny`
+
+Next, construct the signature. The expected signature is computed from the concatenation of:
+
+1. The current epoch timestamp
+2. The `.` character
+3. The JSON response body as a utf-8 encoded string
+
+Hash the string using HMAC SHA256, using the actions secret as the key. The expected signature will be the hex digest of the hash.
+
+Finally, the endpoint should respond with a JSON object containing the following properties:
+
+- `object`: `'authentication_action_response' | 'user_registration_action_response'`
+- `payload`: The JSON response you formed above
+- `signature` The hex digest of the hash you created above
+
+## Test your endpoint
+
+From the dashboard, you can send test actions after configuring an endpoint. Go to the actions _Test_ tab and click the **Send test action** button.
+
+![A screenshot showing how to send a test action in the WorkOS dashboard.](https://images.workoscdn.com/images/8d998ae0-2efa-435a-9818-6873fcdc73ac.png?auto=format&fit=clip&q=80)
+
+If you would like to test against your local development environment, we recommend using a tool like [ngrok](https://ngrok.com) to create a secure tunnel to your local machine, and sending test webhooks to the public endpoint generated with ngrok. See our [blog post](https://workos.com/blog/test-workos-webhooks-locally-ngrok) to get more details on how you may want to test webhooks locally with ngrok.
+
+---

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

@@ -0,0 +1,69 @@
+---
+title: AuthKit
+description: >-
+  Customizable sign-in UI that abstracts away all of the complexity associated
+  with building secure authentication flows.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/authkit.mdx
+---
+
+## Introduction
+
+Implementing authentication flows that handle every possible error state and edge case across multiple identity providers can be a daunting task. AuthKit makes this easy by providing a hosted, pre-built, customizable authentication UI with automatic handling of:
+
+- Sign up, sign in, password reset, and [email verification](/user-management/email-verification) flows.
+- Enterprise [SSO](/user-management/sso) routing and [MFA](/user-management/mfa) enrollment.
+- Automatic bot detection and blocking, to protect against brute force attacks.
+- Customizable [domain](/custom-domains/authkit) and [branding](/user-management/branding).
+
+![AuthKit sign-in UI](https://images.workoscdn.com/images/4d736ca3-eec8-4a90-bd14-2530c4210415.png?auto=format&fit=clip&q=80)
+
+## Authentication flow
+
+AuthKit is conceptually similar to a [Social Login (OAuth)](/user-management/social-login) experience, but with the added benefit of being able to authenticate users with any identity provider.
+
+AuthKit sits outside of your application code. When a user initiates a sign-in request, your application redirects them to the AuthKit URL. The user then completes the authentication process with WorkOS before being returned to the application.
+
+Your application will exchange the resulting authorization code to retrieve an authenticated [User object](/reference/user-management/user) and handle the session.
+
+![AuthKit authentication flow diagram](https://images.workoscdn.com/images/0b3265fa-a209-4ca7-beaf-7d2514a3e00a.png?auto=format&fit=clip&q=80)[border=false]
+
+> The AuthKit flow abstracts away many of the UX and WorkOS API calling concerns automatically, for more guidance on integrating with AuthKit, see the [Quick Start](/user-management) guide.
+
+AuthKit also provides a signup flow for creating users. Available options are determined by the configured [authentication methods](/user-management/authkit/authentication-methods). If a user’s email address is associated with an SSO connection, they will automatically be redirected to sign up via their IdP.
+
+## Authentication methods
+
+AuthKit supports all of the authentication methods available in WorkOS User Management and will automatically adjust the available options depending on the configured methods in the _Authentication_ section of the [WorkOS Dashboard](https://dashboard.workos.com).
+
+![Dashboard displaying available authentication methods](https://images.workoscdn.com/images/ea3b2c3b-723e-462c-aa10-6b1cec1b635f.png?auto=format&fit=clip&q=80)
+
+Email + Password authentication is enabled by default, though set up may be required to enable additional methods. See the relevant feature section for more information:
+
+- [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)
+
+## Custom OAuth static scopes
+
+AuthKit offers support for custom OAuth static scopes for both Google and Microsoft integrations. This allows you to request specific permissions when accessing user profile data from these providers. For instance, requesting access to read Google Calendar events or retrieve emails from a Microsoft account.
+
+> This feature is currently available in a restricted preview. [Contact us](mailto:support@workos.com) for additional details.
+
+---
+
+## Integrating
+
+Integration into your app is quick and easy, though the route you choose varies depending on your specific requirements:
+
+### (A) Integrate with AuthKit
+
+In just a few lines of code, you can add AuthKit to your app and start authenticating users. See the [quick start](/user-management) guide for more information.
+
+### (B) Build your own authentication flows
+
+While the hosted solution is the fastest way to get started, if you’d prefer to build and manage your own authentication UI, you can do so via the [User Management API](/reference/user-management).
+
+Examples of building custom UI are [available on GitHub](https://github.com/workos/authkit).

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

@@ -0,0 +1,143 @@
+---
+title: Branding
+description: Customize AuthKit to fit natively with your app’s unique design.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/branding.mdx
+---
+
+## Introduction
+
+You can customize the look and feel of AuthKit via the _Branding_ section of the [WorkOS Dashboard](https://dashboard.workos.com/branding).
+
+The brand editor allows you to:
+
+- Upload logos and favicons
+- Set brand colors for buttons, links, and backgrounds
+- Manage visual properties such as page layouts, corner radius, and dark mode appearance
+- Include custom ad copy, images, and links to your app’s terms-of-service and privacy policy
+
+The AuthKit preview will update in real-time as you make changes and accurately reflect the available authentication methods, giving you a clear picture of the authentication experience with AuthKit.
+
+![Branding in the Dashboard](https://images.workoscdn.com/images/fc67ec10-44e1-467c-a094-32ed3ff5bd92.png?auto=format&fit=clip&q=80)
+
+## Custom domains
+
+WorkOS supports custom domains for both email and [ACS URLs](/glossary/acs-url). For for information, see the [custom domains documentation](/custom-domains).
+
+## Appearance
+
+AuthKit supports both light and dark mode; each brand configuration option is split across both so that they can be configured independently. You can enforce a specific appearance, or allow the user’s OS system settings to determine which to use.
+
+The corner radius applied to UI elements can also be configured; a lower value will result in a more formal aesthetic while a higher value has a more rounded, playful feel.
+
+![Appearance options highlighted in the branding editor](https://images.workoscdn.com/images/3465072a-87a2-46cc-8577-4e9d4213009a.png?auto=format&fit=clip&q=50)
+
+## Assets
+
+You can upload custom brand assets to display in AuthKit, transactional emails, and the [Admin Portal](/admin-portal).
+
+![Asset options highlighted in the branding editor](https://images.workoscdn.com/images/2a6e77b6-c1fe-4850-a95b-f3e7b7d8bf87.png?auto=format&fit=clip&q=50)
+
+There are three types of assets you can upload:
+
+1. **Logo:** Your full size brand logo, styles vary but this would typically include the wordmark. Must be at least 160x160 px (JPG, PNG, or SVG. 100 KB max size)
+2. **Logo icon:** A smaller, square version of the logo. This is often simply the logomark. Must be at least 160x160 px with a 1:1 aspect ratio (JPG, PNG, or SVG. 100 KB max size)
+3. **Favicon:** A small icon that serves as branding for your website. It is often displayed in the browser tab alongside the address bar. Must be at least 32x32 px with a 1:1 aspect ratio (JPG, PNG, GIF, SVG, WebP, AVIF, or ICO. 100 KB max size)
+
+### Logo style
+
+Either the logo or the logo icon can be displayed in AuthKit. To select which to use, click the logo in the AuthKit preview after uploading both assets.
+
+![Logo selection dialog open in the branding editor](https://images.workoscdn.com/images/2fbd9b69-3434-412b-ab53-e73568f3eb9a.png?auto=format&fit=clip&q=50)
+
+## Color
+
+You can control four colors across light and dark mode:
+
+- Page background color
+- Button background colors
+- Button text color
+- Link color
+
+Other colors used in the UI, like the focus outline, hover styles, or borders, are created automatically based on the four colors you provide, ensuring a consistent look and feel.
+
+![Color options in the branding editor](https://images.workoscdn.com/images/b6a2eb40-2510-4e54-bdca-0c91953fb84d.png?auto=format&fit=clip&q=50)
+
+## Copy
+
+The page title and alternate action link text on AuthKit pages can be customized to fit your brand’s tone of voice. They can be edited directly inside the AuthKit preview pane.
+
+> An _alternate action_ refers to the action a user will take to navigate between AuthKit pages. For example, if a user is on the sign-in page and they don’t have an account, the alternate action will navigate to the signup page.
+
+Start by selecting the page you want to edit. Then, click on the text you want to change from the preview pane.
+
+![AuthKit page selector in the branding editor](https://images.workoscdn.com/images/6b2c0b3d-9f2f-404f-a893-23c3ec8a2d6f.png?auto=format&fit=clip&q=50)
+
+![Text customization highlighted in the branding editor](https://images.workoscdn.com/images/07734ffb-c639-4abd-8d99-bd1feb9d5eda.png?auto=format&fit=clip&q=50)
+
+## Page settings
+
+AuthKit pages can optionally display a link to your app’s privacy policy and/or terms-of-service. The link will then appear below the authentication form.
+
+AuthKit also allows you to choose whether or not first name and last names are required when signing up. To toggle either of these, select the _Page Settings_ panel and update the respective field.
+
+![Page settings in the branding editor](https://images.workoscdn.com/images/6b2e6b35-5658-42ab-8c6a-6b6aa0d9b381.png?auto=format&fit=clip&q=80)
+
+## Page layout
+
+The layout for AuthKit pages can be customized to fit your brand’s needs. You can choose between a centered, one-column layout, or a two-column layout using [custom HTML and CSS](#custom-code-details-and-limitations) for the secondary column.
+
+![Page settings in the branding editor](https://images.workoscdn.com/images/70acf0d4-caf8-435e-bedd-1960e8cd27c4.png?auto=format&fit=clip&q=80)
+
+### Split layouts
+
+Split page layouts allow you to add a secondary panel on AuthKit pages that can be customized with HTML and CSS. This can be used to display marketing content or decorative elements on the page.
+
+To enable this feature, select the page you want to customize. Then, select the _Split_ layout option under _Page Settings_. The secondary panel can be displayed to the left or right of the primary panel, and optionally hidden on mobile devices.
+
+![Split layout setting in the branding editor](https://images.workoscdn.com/images/057b92eb-bf5d-4832-b8c3-33f470e766f1.png?auto=format&fit=clip&q=80)
+
+Click on the secondary column from the preview pane. This will open a dialog where you can enter your HTML and CSS.
+
+![Custom code editor dialog in the branding editor](https://images.workoscdn.com/images/e0c512c9-dee0-470b-aa55-7d89c1b44a5c.png?auto=format&fit=clip&q=80)
+
+### Custom code details and limitations
+
+Any HTML and CSS entered into the custom code dialog will only be applied to the secondary column of the selected page. This allows you a high level of flexibility without impacting content elsewhere on the page.
+
+For security purposes, all code input is sanitized and stripped of any potentially harmful elements. This means that you can’t use JavaScript or any other dynamic content in your HTML. This includes `script`, `iframe`, `form`, and `object` elements—as well as inline event handlers for any elements.
+
+For example, the following code will be sanitized from this:
+
+```html
+<h1 onclick="onClick()">Welcome to SuperApp</h1>
+<script>
+  const onClick = () => alert('Warning!');
+</script>
+```
+
+…to this:
+
+```html
+<h1>Welcome to SuperApp</h1>
+```
+
+HTML `style` elements will also be removed to prevent overriding any content outside of the secondary panel. All custom CSS should be entered into the CSS editor.
+
+CSS selectors will be scoped to the secondary column via [CSS nesting](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_nesting/Using_CSS_nesting). For compatibility with older browsers, we use a light transform step to convert the nested CSS to a flat structure.
+
+For example, the following CSS will be transformed from this:
+
+```css
+h1 {
+  color: var(--primary-color);
+}
+```
+
+…to this:
+
+```css
+:where([data-hak-custom-html]) h1 {
+  color: var(--primary-color);
+}
+```

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

@@ -0,0 +1,110 @@
+---
+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/custom-emails.mdx

@@ -0,0 +1,164 @@
+---
+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
+---
+
+## 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.
+
+---
+
+## Disabling default emails
+
+To change email settings for an environment, navigate to _Authentication_ → _Emails_ and select _Configure emails_. You should have an **Admin** role for to update this setting.
+
+![A screenshot showing the WorkOS Dashboard configuration card for emails](https://images.workoscdn.com/images/01c99f2b-8813-4c72-9480-9898e1dabd4a.png?auto=format&fit=clip&q=80)
+
+![A screenshot showing the WorkOS Dashboard dialog for email settings](https://images.workoscdn.com/images/7b4f4713-3381-49aa-b77c-679c9698b429.png?auto=format&fit=clip&q=80)
+
+---
+
+## Invitations
+
+Once you've turned off the default user invitation emails, use the information below to send custom invitation emails.
+
+**[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)**
+: Used to retrieve the invitation object from the ID in the invitation created event.
+
+**[Send Invitation API](/reference/user-management/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).
+
+![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) Handle manually creating invitations {{ "visibility": "no-quick-nav" }}
+
+If you’re creating invitations using the WorkOS dashboard, you’ll need to handle `invitation.created` events using the events API or webhooks.
+
+Due to security concerns, the events do not contain the sensitive information you’ll need to send the email. To retrieve the full invitation object with this information, use the invitation ID from the event to call the Get Invitation API.
+
+You can skip this step if you don't plan to create the invitations manually in the dashboard.
+
+### (B) Handle invitations created via the API {{ "visibility": "no-quick-nav" }}
+
+If you’re creating invites via the Send Invitation API, you can send your own email using the information returned in the invitation object.
+
+If you also plan to create invitations manually in the dashboard, you can just handle `invitation.created` events as described above.
+
+### Send your email {{ "visibility": "no-quick-nav" }}
+
+The recipient of the email should match the `email` attribute in the invitation object retrieved via the API. The body of the email should include a link where the user can accept the invitation. For most use cases, you can use the `accept_invitation_url` as this link.
+
+If you are building your own authentication app, and your invitation acceptance path diverges from this pattern, you may want to construct your own URL with the `token`, rather than using the `accept_invitation_url`.
+
+Additionally, if the invitation object contains an organization ID and/or an inviter user ID, you may want to include that information in the body of the email.
+
+---
+
+## Magic Auth
+
+Once you've turned off the default Magic Auth emails, use the information below to send custom Magic Auth emails.
+
+**[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)**
+: 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)**
+: 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" }}
+
+If you are using AuthKit, you’ll need to handle `magic_auth.created` events, using the events API or webhooks.
+
+Due to security concerns, the events do not contain the sensitive information you’ll need to send the email. To retrieve the full Magic Auth object with this information, use the Magic Auth ID from the event to call the Get Magic Auth API.
+
+You can skip this step if you're building your own authentication app.
+
+### (B) Handle Magic Auth codes created via the API {{ "visibility": "no-quick-nav" }}
+
+If you’re initiating Magic Auth authentication via the Create Magic Auth API, you can send your own email using the information returned in the Magic Auth object.
+
+### Send your email {{ "visibility": "no-quick-nav" }}
+
+The recipient of the email should match the `email` attribute for the Magic Auth object retrieved via the API, and the email should include the `code`. Recipients will input that code into AuthKit, or your own authentication UI, to authenticate into your application via Magic Auth.
+
+---
+
+## Email verification
+
+Once you've turned off the default email verification emails, use the information below to send custom email verification emails.
+
+**[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)**
+: 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)**
+: 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" }}
+
+If you are using AuthKit, you’ll need to handle `email_verification.created` events, using the events API or webhooks.
+
+Due to security concerns, the events do not contain the sensitive information you’ll need to send the email. To retrieve the full email verification object with this information, use the email verification ID from the event to call the Get Email Verification API.
+
+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.
+
+### Send your email {{ "visibility": "no-quick-nav" }}
+
+The recipient of the email should match the `email` attribute for the email verification object retrieved via the API, and the email should include the `code`. Recipients will input that code into AuthKit, or your own authentication UI, to verify their email.
+
+---
+
+## Password reset
+
+Once you've turned off the default password reset emails, use the information below to send custom password reset emails.
+
+**[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)**
+: 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)**
+: 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).
+
+![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) Handle password resets created via AuthKit {{ "visibility": "no-quick-nav" }}
+
+If you are using AuthKit, you’ll need to handle `password_reset.created` events, using the events API or webhooks.
+
+Due to security concerns, the events do not contain the sensitive information you’ll need to send the email. To retrieve the full password reset object with this information, use the password reset ID from the event to call the Get Password Reset API.
+
+You can skip this step if you're building your own authentication app.
+
+### (B) Handle password resets created via the API {{ "visibility": "no-quick-nav" }}
+
+If you’re creating password resets via the Create Password Reset API, you can send your own email using the information returned in the password reset object.
+
+### Send your email {{ "visibility": "no-quick-nav" }}
+
+The recipient of the email should be the `email` attribute in the password reset object retrieved via the API. The body of the email should include a link where the user can reset their password. For most use cases, you can use the `password_reset_url` as this link.
+
+If you're building your own authentication app, and your password reset path diverges from this pattern, you may want to construct your own URL with the `password_reset_token`, rather than using the `password_reset_url`.