@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/migrate/standalone-sso.mdx

@@ -0,0 +1,105 @@
+---
+title: Migrate from the standalone SSO API
+description: Learn how to migrate your code from an existing WorkOS SSO integration.
+breadcrumb:
+  title: Migrations
+  url: /migrate
+originalPath: .tmp-workos-clone/packages/docs/content/migrate/standalone-sso.mdx
+---
+
+## Introduction
+
+The WorkOS User Management API supports all of the same social and enterprise identity providers, while providing higher level authentication features that most applications need. In this guide, we’ll outline the steps to migrate an existing WorkOS SSO integration to the User Management API.
+
+> The existing standalone [WorkOS SSO API](/reference/sso) will continue to be supported. This is a viable option for you if you prefer to handle more of the authentication flow yourself.
+
+## The new User resource
+
+The primary difference between existing integrations with [SSO](/sso) or [Directory Sync](/directory-sync) is the addition of a new resource: [Users](/reference/user-management/user).
+
+The WorkOS [User object](/reference/user-management/user) represents a single user in your application, and binds together information from all of the Directory and Identity providers that WorkOS supports into a single resource. As you migrate your existing integration, you can expect to replace references to WorkOS Profiles and Directory Users with instead references to Users.
+
+## Switch to User Management API calls
+
+If you have built an integration with our standalone SSO API using [Get Authorization URL](/reference/sso/get-authorization-url), you will need to switch these calls with analogous calls to the User Management API.
+
+### (1) Switch SSO initiation call
+
+When initiating SSO for one of your users, instead of calling the SSO [Get Authorization URL](/reference/sso/get-authorization-url) API, call the User Management [Get Authorization URL](/reference/user-management/authentication/get-authorization-url) API instead:
+
+<CodeBlock title="Update Initiation Calls">
+  <CodeBlockTab
+    language="js"
+    file="initiation-call-next.trunk-ignore"
+    title="Next.js"
+  />
+  <CodeBlockTab
+    language="js"
+    file="initiation-call-express.trunk-ignore"
+    title="Express"
+  />
+</CodeBlock>
+
+The User Management Get Authorization API supports all of the same initiation parameters as the old API. In addition, it also supports an additional provider type, `authkit`, which will be covered later in this guide.
+
+### (2) Switch API in Application Callback
+
+Similar to an SSO integration, your application will still have a callback identified by the Redirect URI passed during the previous initiation call. The contract with your callback is the same, where you should expect to be given a `code`, along with any `state` that was originally provided.
+
+However, instead of calling the SSO [Get a Profile and Token](/reference/sso/profile/get-profile-and-token) API, call the User Management [Authenticate](/reference/user-management/authentication) API instead, with the `grant_type` set to `authorization_code`:
+
+<CodeBlock title="Update Application Callback">
+  <CodeBlockTab
+    language="js"
+    file="application-callback-next.trunk-ignore"
+    title="Next.js"
+  />
+  <CodeBlockTab
+    language="js"
+    file="application-callback-express.trunk-ignore"
+    title="Express"
+  />
+</CodeBlock>
+
+> **Important:** Instead of receiving a [Profile](/reference/sso/profile), your application now receives a full [User object](/reference/user-management/user). While many of the fields are similar, such as the user’s email or name, the **User ID’s will be different** than the Profile ID’s you may have previously persisted in your application.
+
+If email is a unique identifier in your application, you can use the WorkOS User’s email to identify the application-local user. WorkOS ensures that user email is verified before successfully completing an authentication request. When the API issues an email verification challenge, an [email verification response](/reference/user-management/authentication-errors/email-verification-required-error) is returned.
+
+### Handling new authentication flows
+
+The User Management API offers a higher-level abstraction than the SSO API, offering more advanced [security features](/user-management/overview/security) like email verification and account Linking.
+
+This means that when your application attempts to exchange a code for a user object, it may return one of several new expected errors. These map to cases that were previously mentioned, like requiring that the user first verify their email, or enroll in MFA.
+
+If your application doesn’t require these extra settings, they can be disabled in the _Authentication_ section of the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+> If you are using AuthKit, you won’t need to handle error cases like required email verification, as AuthKit will automatically request this before a user is directed to their callback endpoint.
+
+## AuthKit
+
+If you prefer to have full control over the authentication UI, you can choose to integrate with the User Management API directly. However, the easiest way to get started is to use AuthKit, a pre-built hosted authentication UI that supports guiding users through all of the advanced flows, like email verification, MFA enrollment + verification, and identity linking.
+
+You can enable AuthKit from the WorkOS dashboard, where you can also configure AuthKit branding and custom domains.
+
+Getting started with AuthKit is as simple as passing `authkit` as the `provider`:
+
+<CodeBlock title="AuthKit Initiation callback">
+  <CodeBlockTab language="js" file="authkit-initiation-next" title="Next.js" />
+  <CodeBlockTab
+    language="js"
+    file="authkit-initiation-express"
+    title="Express"
+  />
+</CodeBlock>
+
+AuthKit can handle many of the concerns your application likely needed to previously, such as identifying which users sign in using enterprise SSO, and correctly routing them to their organization’s identity provider.
+
+## Directory Sync
+
+Directory provisioning is also supported in User Management. See the [Directory Provisioning documentation](/user-management/directory-provisioning) to learn more.
+
+## Next Steps
+
+Check out the [full guide](/user-management), along with the [API reference](/reference/user-management) to get an idea of all the ways your application’s user management needs can be solved by WorkOS.
+
+If you need help migrating your existing WorkOS integration, or have any other questions, please reach out to [WorkOS support](mailto:support@workos.com?subject=WorkOS%20Support).

package/.docs/organized/docs/on-prem-deployment.mdx

@@ -0,0 +1,119 @@
+---
+title: Using WorkOS with On-prem Customers
+description: Best practices for using WorkOS with on-prem customers.
+breadcrumb:
+  title: Home
+  url: /
+originalPath: .tmp-workos-clone/packages/docs/content/on-prem-deployment.mdx
+---
+
+## Introduction
+
+WorkOS can be used with both cloud and on-prem deployments. This guide explains the considerations needed to use WorkOS features with on-prem deployment strategies. For example, many SaaS companies offer enterprise solutions where their infrastructure can be deployed to a customer's cloud or data center.
+
+When using an on-prem deployment strategy, two key considerations are:
+
+- Deploying a static API key to each customer's installation to isolate access to their team only
+- Ensuring your customer's network can send and receive requests from the WorkOS API
+
+Outside of these considerations, WorkOS integration for on-prem customers functions in the same way as in cloud deployments.
+
+![diagram showing on-prem configuration using WorkOS](https://images.workoscdn.com/images/17460e43-790f-4791-93ee-f0b001ef5eae.png?auto=format&fit=clip&q=50)
+
+## Using a static API key for each customer's deployment
+
+Since a full deployment of your software is being deployed to your customer's environment, each deployment requires its own unique WorkOS API key. This can be accomplished by creating a separate environment in your WorkOS dashboard for each on-prem customer.
+
+Each WorkOS workspace comes with Staging and Production environments by default. To create a new environment for an on-prem customer:
+
+- Reach out to the WorkOS support team at [support@workos.com](mailto:support@workos.com)
+- Provide the name you'd like to use for the new environment and specify that it should be a production environment
+
+![diagram showing different environments in the WorkOS dashboard](https://images.workoscdn.com/images/2e280efe-011f-4583-9c67-1fedd60f0071.png?auto=format&fit=clip&q=50)
+
+The support team will create the environment, which will then be available in the environments dropdown menu in your WorkOS workspace.
+
+To retrieve the client ID and API key for this environment, navigate to the [API Keys section](https://dashboard.workos.com/api-keys) of the WorkOS dashboard where the values are available to download.
+
+## Allowing WorkOS Traffic Through Firewalls
+
+A common challenge with on-premise deployments is coordinating which traffic will be allowed by the firewall. Several strategies exist for allowing traffic to and from WorkOS to communicate with an on-prem deployment.
+
+### Strategy 1: Configure Firewall Rules or ACLs
+
+The most common approach is to deploy your application with the WorkOS integration to your customer's on-prem environment configured the same as you would for cloud application users, then have the firewall rules or access control lists (ACLs) set to allow WorkOS API traffic.
+
+WorkOS uses Cloudflare to ensure security and reliability. If you need to allowlist IP addresses for redirect requests, you can use the IP ranges listed in the [Cloudflare documentation](https://www.cloudflare.com/ips/).
+
+![diagram showing different environments in the WorkOS dashboard](https://images.workoscdn.com/images/23e605b6-2b82-41be-a93b-664d07b07d0a.png?auto=format&fit=clip&q=50)
+
+#### Firewall Ingress Rules (Incoming Traffic)
+
+Ingress rules control external traffic entering your network. Some features of WorkOS require requests originating from our APIs directly to the on-prem installation, such as authentication callbacks, action callbacks, and webhooks.
+
+Events can also be ingested with the Events API, which is the preferred method for event delivery in an on-prem deployment scenario since those requests will originate from your on-prem application infrastructure.
+
+- All requests use HTTPS on port 443
+- All authentication requests originate from [Cloudflare's published IP ranges](https://www.cloudflare.com/ips/)
+- All outbound requests for [Actions Webhooks](/user-management/actions) and [event and log streaming](/events/observability/datadog) will originate from the following IP ranges:
+
+  - 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
+
+- Requests will require an external domain name that resolves to the installation's host
+
+#### Firewall Egress Rules (Outgoing Traffic)
+
+Egress rules manage traffic leaving your network to external services.
+
+Key aspects include:
+
+- All requests leave the on-prem network over HTTPS on port 443
+- All traffic is handled on Cloudflare's published IP ranges
+
+##### Best Practices
+
+- Apply the principle of least privilege
+- Log and monitor cross-boundary traffic
+- Regularly audit firewall rules
+
+Implement a workflow of starting with restrictive default deny rules, then carefully opening only necessary ports and protocols to ensure that your integration with WorkOS is secure.
+
+### Strategy 2: Use ngrok for Network Traffic Management
+
+Another approach is to use a service like [ngrok](https://ngrok.com/) to manage traffic to and from the WorkOS API instead of modifying firewall rules. This approach allows you to implement WorkOS authentication without adjusting firewall configurations.
+
+With ngrok, you can:
+
+- Create secure tunnels from the public internet to your on-premise deployment
+- Receive webhook events from WorkOS directly to your local development environment
+- Implement WorkOS AuthKit, SSO and Directory Sync features in environments with restrictive network policies
+
+Implementation involves installing the ngrok client on your application server, establishing a tunnel to your application's local port, and configuring your WorkOS integration to use the ngrok-provided public URL.
+
+![diagram showing a WorkOS on-prem configuration using ngrok ](https://images.workoscdn.com/images/42766c0c-741c-460f-818f-6bb4875634ca.png?auto=format&fit=clip&q=50)
+
+This approach requires configuration of third-party software and additional cost. ngrok offers different pricing tiers based on your needs, with paid plans providing features like persistent URLs, IP restrictions, and additional security controls essential for production environments.
+
+## Air-Gapped Environments
+
+For customers operating in air-gapped environments with no external network connectivity, cloud-based authentication services like WorkOS cannot be utilized as they require API connectivity.
+
+However, many organizations with air-gapped environments have established security protocols that permit the deployment of approved third-party software within their isolated networks, as their security architecture already provides robust authentication mechanisms internally.
+
+In these scenarios, we recommend a dual-implementation approach:
+
+- Continue leveraging WorkOS for authentication in cloud-based and network-connected on-premises deployments
+- Develop a specialized deployment package for air-gapped environments that:
+  - Integrates with the customer's existing internal authentication infrastructure
+  - Maintains feature parity while operating independently of external services
+  - Adheres to the security policies specific to air-gapped environments
+
+This approach allows you to maintain a consistent product experience across different deployment scenarios while accommodating the strict security requirements of air-gapped customers.

package/.docs/organized/docs/postman.mdx

@@ -0,0 +1,90 @@
+---
+title: WorkOS Postman collection
+description: Test the WorkOS API with Postman.
+breadcrumb:
+  title: Home
+  url: /
+originalPath: .tmp-workos-clone/packages/docs/content/postman.mdx
+---
+
+## Introduction
+
+Postman is a popular API development tool that allows users to easily test API endpoints. The [WorkOS API collection](https://www.postman.com/workos/workspace/workos-public/collection/25188762-79ce1172-4741-4f1d-a486-64380f9a599f?ctx=documentation) is a set of pre-configured requests specific to the WorkOS API, meant to help developers to quickly get started testing the WorkOS API endpoints.
+
+The [environment template](https://www.postman.com/workos/workspace/workos-public/environment/25188762-b99e7518-d907-4aa0-82d2-a199157a53c7) supports this collection, and allows variables to be abstracted away from the individual requests. The environment template makes it easier to manage and re-use common variables across the collection’s requests.
+
+## Configuring Postman
+
+There are several ways to use this collection. You can create a fork, or you can export/import the collection and environment.
+
+### Creating a fork
+
+The preferred and simplest way to get started using the WorkOS API collection is to create a fork of the collection and environment.
+
+To create a fork of the collection, first sign in to your Postman account. Then navigate to the WorkOS API collection. Hover over the name of the collection and click the three dots, then click "Create a fork".
+
+![A screenshot showing how to fork a collection in Postman](https://images.workoscdn.com/images/a3d67b02-a824-4f27-b055-c06eaf5a7e94.png?auto=format&fit=clip&q=50)
+
+Select your fork label and workspace, then click the "Fork collection" button.
+
+![A screenshot showing the fork collection details page in Postman.](https://images.workoscdn.com/images/c9074bd3-8ab8-4864-9b68-56c6a858a17e.png?auto=format&fit=clip&q=50)
+
+You will now see the WorkOS API collection appear in your workspace’s collection tab.
+
+To fork the WorkOS environment template, the same process is used. Navigate to the environments tab of the WorkOS Public workspace. Hover over the WorkOS environment template, click the three dots, and then click "Create a fork". Select your fork label and workspace, then click the "Fork environment" button.
+
+### Exporting the collection and environment
+
+Another way to use the WorkOS API collection is to import the collection and environment into your workspace. Using this approach allows you to share the collection as a JSON file to easily share it with others.
+
+To export the collection, navigate to the collection tab in the WorkOS workspace, then hover over the WorkOS API collection name and click on the three dots. Click export to download the collection as a JSON file.
+
+![A screenshot showing the export option in Postman.](https://images.workoscdn.com/images/54aed639-6c8f-467e-baa6-53099c36fe35.png?auto=format&fit=clip&q=50)
+
+Navigate to your workspace’s collections tab and click on the import button.
+
+![A screenshot showing where to find the import button in Postman.](https://images.workoscdn.com/images/802d9d45-c258-4548-9f88-7d04f2d260c2.png?auto=format&fit=clip&q=50)
+
+Select the JSON file that was downloaded in the previous step and then click import. You will now see the collection available to use and edit in the collection tab.
+
+The environment can be exported from the WorkOS workspace and imported to your personal workspace using these same steps.
+
+Navigate to the collection tab in your workspace and select the environment. This allows the collection to reference the environment variables.
+
+## Environment variables
+
+The WorkOS API collection makes use of environment variables. All environment variables that are used in the WorkOS API collection are defined in the environment tab in Postman.
+
+![A screenshot showing the environments tab in Postman.](https://images.workoscdn.com/images/bd26c85b-8d66-478c-909b-f5ee01ffaffd.png?auto=format&fit=clip&q=50)
+
+To get started, you will need to obtain the `api_key` and `client_id` values from your WorkOS dashboard and enter them in the environment template.
+
+You can find your API key and the client ID on the [API Keys](https://dashboard.workos.com/api-keys) page in the WorkOS dashboard.
+
+There are also several other environment variables in the template which will need to be replaced with various IDs and values in the course of making API calls. These values are defined in the variable descriptions.
+
+## Sending requests to the WorkOS API
+
+The WorkOS collection sends data in several ways. Some requests use values directly in the URL, some requests use query parameters, and some requests send data in the body of the request. Each call will indicate where there are values present with a green dot.
+
+The "Get A Directory User" request for instance uses the `api_key` environment variable in the authorization tab of the request, and the `base_url` and `directory_user_id` values in the URL of the request.
+
+![A screenshot showing the Get a Directory User request in Postman.](https://images.workoscdn.com/images/76d3df52-cf4e-467a-a898-df62a920a800.png?auto=format&fit=clip&q=50)
+
+The "Generate a Portal Link" request uses the `base_url` and `api_key` variables in the same way that the Get A Directory User call does, but also sends the name of the Organization and intent in the body of the request as x-www-form-urlencoded data.
+
+![A screenshot showing the Generate a Portal Link request in Postman.](https://images.workoscdn.com/images/c2ae7131-dc79-49ee-aac1-724d3de42c48.png?auto=format&fit=clip&q=50)
+
+To send a request, first select the WorkOS environment template so the collection has access to its variables.
+
+![A screenshot showing where to select the Environment in Postman.](https://images.workoscdn.com/images/fea5d174-0fea-400b-b498-3753c85c5eeb.png?auto=format&fit=clip&q=50)
+
+Finally, ensure all the values are defined where they are needed for the particular request and then click send.
+
+## Debugging requests
+
+Postman provides a developer console if you need to debug any requests. Navigate to a request and click on the console button to view the details of the requests you send.
+
+![A screenshot showing the developer console in Postman.](https://images.workoscdn.com/images/9dafe4a0-5a9a-46d3-bee9-ba01d5b25724.png?auto=format&fit=clip&q=50)
+
+If you have any questions while using the WorkOS API collection, please reach out to our team at [support@workos.com](mailto:support@workos.com).