@workos/mcp-docs-server 0.1.0

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

@@ -0,0 +1,525 @@
+---
+title: User Management
+description: >-
+  Easy to use authentication APIs designed to provide a flexible, secure, and
+  fast integration.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/index.mdx
+---
+
+## Introduction {{ "visibility": "no-quick-nav" }}
+
+Integrating User Management features into your app is quick and easy. In this guide, we’ll walk you through adding a hosted authentication flow to your application using [AuthKit](/user-management/authkit).
+
+In addition to this guide, there are a variety of [example apps](/user-management/example-apps) available to help with your integration.
+
+## Before getting started {{ "visibility": "no-quick-nav" }}
+
+To get the most out of this guide, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+- Your WorkOS [API Key](/glossary/api-key) and [Client ID](/glossary/client-id)
+
+Additionally you'll need to activate User Management in your WorkOS Dashboard if you haven't already. In the _Overview_ section, click the _Set up User Management_ button and follow the instructions.
+
+![WorkOS dashboard with the User Management setup button highlighted](https://images.workoscdn.com/images/01c528be-f3ed-416d-b1c4-9f8cf923d138.png?auto=format&fit=clip&q=50)
+
+---
+
+## (1) Configure your project
+
+Let’s add the necessary dependencies and configuration in your WorkOS Dashboard.
+
+<StackSelection />
+
+### Install dependencies
+
+- $ frontend="client-only"
+
+  For a client-only approach, use the `authkit-react` library to integrate AuthKit directly into your React application. Start by installing the library to your project via `npm`.
+
+  ```bash title="Install React SDK"
+  npm install @workos-inc/authkit-react
+  ```
+
+- $ frontend="nextjs"
+
+  For a Next.js integration, use the `authkit-nextjs` library. Start by installing it in your Next.js project via `npm`.
+
+  ```bash title="Install Next.js SDK"
+  npm install @workos-inc/authkit-nextjs
+  ```
+
+- $ frontend="remix"
+
+  To use AuthKit with a Remix application, use the `authkit-remix` library. Start by installing it in your Remix project via `npm`.
+
+  ```bash title="Install Remix SDK"
+  npm install @workos-inc/authkit-remix
+  ```
+
+- $ backend="nodejs"
+
+  First, install the required Node SDK via `npm`.
+
+  ```bash title="Install Node SDK"
+  npm install @workos-inc/node
+  ```
+
+- $ backend="ruby"
+  First, install the WorkOS gem.
+
+  ```bash title="Install Ruby SDK"
+  gem install workos
+  ```
+
+- $ backend="python"
+
+  First, install the Python SDK.
+
+  ```bash title="Install Python SDK"
+  pip install workos
+  ```
+
+### Configure a redirect URI
+
+A redirect URI is a callback endpoint that WorkOS will redirect to after a user has authenticated. This endpoint will exchange the authorization code returned by WorkOS for an authenticated [User object](/reference/user-management/user). We’ll create this endpoint in the next step.
+
+You can set a redirect URI in the _Redirects_ section of the [WorkOS Dashboard](https://dashboard.workos.com). While [wildcards](/sso/redirect-uris/wildcard-characters) in your URIs can be used in the staging environment, they and query parameters cannot be used in production.
+
+- $ frontend="client-only"
+
+  ![Dashboard redirect URI](https://images.workoscdn.com/images/1ca70f77-a7d1-4320-aa24-732dc77e89de.png?auto=format&fit=clip&q=50)
+
+  > For the client-only integration, make sure to set the callback URI as the same route where you require auth.
+
+- $ frontend="nextjs, remix, vanilla, react"
+
+  ![Dashboard redirect URI](https://images.workoscdn.com/images/58232e3c-ab9f-41cc-99f4-1692214073fa.png?auto=format&fit=clip&q=80)
+
+When users sign out of their application, they will be redirected to your app's [Logout redirect](/user-management/sessions/configuring-sessions/logout-redirect) location which is configured in the same dashboard area.
+
+### Configure initiate login URL
+
+- $ frontend="client-only"
+
+  All login requests must originate at your application for the [PKCE](/reference/user-management/authentication/get-authorization-url/pkce) code exchange to work properly. In some instances, requests may not begin at your app. For example, some users might bookmark the hosted login page or they might be led directly to the hosted login page when clicking on a password reset link in an email.
+
+- $ frontend="nextjs, remix, vanilla, react"
+
+  Login requests should originate from your application. In some instances, requests may not begin at your app. For example, some users might bookmark the hosted login page or they might be led directly to the hosted login page when clicking on a password reset link in an email.
+
+In these cases, AuthKit will detect when a login request did not originate at your application and redirect to your application’s login endpoint. This is an endpoint that you define at your application that redirects users to sign in using AuthKit. We’ll create this endpoint in the next step.
+
+You can configure the initiate login URL from the _Redirects_ section of the WorkOS dashboard.
+
+![Initiate login URL](https://images.workoscdn.com/images/ab7099e9-5577-4c53-afdb-e601f1e920ad.png?auto=format&fit=clip&q=50)
+
+- $ frontend="client-only"
+
+  ### Configure CORS
+
+  Since your user's browser will be making calls to the WorkOS API directly, it is necessary to add your domain to the allow list in your WorkOS Settings. This can be configured in the _Configure CORS_ dialog on the _Authentication_ page of the WorkOS dashboard.
+
+  ![Screenshot of the WorkOS dashboard showing the "Configure CORS" option in the "Authentication" section.](https://images.workoscdn.com/images/3b7863df-8c59-4d48-ab91-f537fd5c9f66.png?auto=format&fit=clip&q=50)
+
+  While building your integration in the Staging environment you should add your local development URL here. In the example below we're adding `http://localhost:5173` to the list of allowed web origins.
+
+  ![Screenshot of the WorkOS dashboard showing the CORS configuration panel.](https://images.workoscdn.com/images/e20fdbfb-965f-47b5-9c64-b83f6e6b8a39.png?auto=format&fit=clip&q=50)
+
+- $ frontend="nextjs, remix"
+
+  ### Set secrets
+
+  To make calls to WorkOS, provide the API key and the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app's configuration depending on your preferences.
+
+- $ frontend="nextjs"
+
+  ```plain title="Environment variables"
+  WORKOS_API_KEY='sk_example_123456789'
+  WORKOS_CLIENT_ID='client_123456789'
+  WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here
+
+  # configured in the WorkOS dashboard
+  NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:3000/callback"
+  ```
+
+  The `NEXT_PUBLIC_WORKOS_REDIRECT_URI` uses the `NEXT_PUBLIC` prefix so the variable is accessible in edge functions and middleware configurations. This is useful for configuring operations like Vercel preview deployments.
+
+- $ frontend="remix"
+
+  ```plain title="Environment variables"
+  WORKOS_API_KEY='sk_example_123456789'
+  WORKOS_CLIENT_ID='client_123456789'
+
+  WORKOS_REDIRECT_URI="http://localhost:3000/callback" # configured in the WorkOS dashboard
+  WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here
+  ```
+
+- $ frontend="nextjs, remix"
+
+  The SDK requires you to set a strong password to encrypt cookies. This password must be at least 32 characters long. You can generate a secure password by using the [1Password generator](https://1password.com/password-generator/) or the `openssl` library via the command line:
+
+  ```bash title="Generate a strong password"
+  openssl rand -base64 32
+  ```
+
+- $ backend="nodejs, ruby, python"
+
+  ### Set secrets
+
+  To make calls to WorkOS, provide the API key and the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app's configuration depending on your preferences.
+
+  ```plain title="Environment variables"
+  WORKOS_API_KEY='sk_example_123456789'
+  WORKOS_CLIENT_ID='client_123456789'
+  ```
+
+> The code examples use your staging API keys when [signed in](https://dashboard.workos.com)
+
+---
+
+## (2) Add AuthKit to your app
+
+Let’s integrate the hosted authentication flow into your app.
+
+- $ frontend="client-only"
+
+  ### Wrap your app with the AuthKit provider
+
+  The `AuthKitProvider` component will handle the redirect from Hosted AuthKit, refresh the session when needed and provide context for hooks used in the components of your app. Initialize it with your client ID, which you can find in the WorkOS dashboard. You should also specify your custom authentication API domain.
+
+  > If you have not set up a custom authentication domain in WorkOS, set `devMode={true}` on `<AuthKitProvider />`. This will keep the refresh token in local storage instead of a secure, HTTP-only cookie.
+
+  <CodeBlock file="client-only-provider" title="/app/root.tsx" />
+
+  > For security reasons, the client-only integration cannot be nested inside an `iframe`.
+
+  ### Use the auth hook in your components
+
+  The `useAuth` hook will return user information and loading status. It also provides functions to retrieve the access token and sign in and sign out the user.
+
+  <CodeBlock file="authkit-react-example-full" title="/app.jsx" />
+
+  ### Protect routes with custom hooks
+
+  If you have routes that you wish to only be accessible to logged in users, you can use a custom React hook.
+
+  <CodeBlock file="use-user-hook" title="/hooks/use-user.ts" />
+
+  Then use that hook to protect your mandatory sign in routes.
+
+  <CodeBlock file="client-only-protected-route" title="/app/protected.jsx" />
+
+- $ frontend="nextjs"
+
+  ### Provider
+
+  The `AuthKitProvider` component adds protections for auth edge cases and is required to wrap your app layout.
+
+  <CodeBlock file="authkit-nextjs-provider" title="/app/layout.tsx" />
+
+  ### Middleware
+
+  [Next.js middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware) is required to determine which routes require authentication.
+
+  #### Implementing the middleware
+
+  When implementing, you can opt to use either the complete `authkitMiddleware` solution or the composable `authkit` method. You'd use the former in cases where your middleware is only used for authentication. The latter is used for more complex apps where you want to have your middleware perform tasks in addition to auth.
+
+  - | Complete
+
+    The middleware can be implemented in the `middleware.ts` file. This is a full middleware solution that handles all the auth logic including session management and redirects for you.
+
+    With the complete middleware solution, you can choose between page based auth and middleware auth.
+
+    #### Page based auth
+
+    Protected routes are determined via the use of the `withAuth` method, specifically whether the `ensureSignedIn` option is used. Usage of `withAuth` is covered further down in the _Access authentication data_ section.
+
+    <CodeBlock file="authkit-nextjs-middleware" title="middleware.ts" />
+
+    #### Middleware auth
+
+    In this mode the middleware is used to protect all routes by default, redirecting users to AuthKit if no session is available. Exceptions can be configured via an allow list.
+
+    <CodeBlock
+      file="authkit-nextjs-middleware-auth-mode"
+      title="middleware.ts"
+    />
+
+    In the above example, the home page `/` can be viewed by unauthenticated users. The `/account` page and its children can only be viewed by authenticated users.
+
+  - | Composable
+
+    The middleware can be implemented in the `middleware.ts` file. This is a composable middleware solution that handles the session management part for you but leaves the redirect and route protection logic to you.
+
+    <CodeBlock
+      file="authkit-nextjs-middleware-composable"
+      title="middleware.ts"
+    />
+
+  ### Callback route
+
+  When a user has authenticated via AuthKit, they will be redirected to your app's callback route. Make sure this route matches the `WORKOS_REDIRECT_URI` environment variable and the configured redirect URI in your WorkOS dashboard.
+
+  <CodeBlock file="callback-endpoint-nextjs" title="/app/callback/route.ts" />
+
+  ### Initiate login route
+
+  We'll need an initiate login endpoint to direct users to sign in using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.
+
+  <CodeBlock
+    file="initiate-login-endpoint-nextjs"
+    title="/app/login/route.ts"
+  />
+
+  ### Access authentication data
+
+  AuthKit can be used in both server and client components.
+
+  - | Server component
+
+    The `withAuth` method is used to retrieve the current logged in user and their details.
+
+    <CodeBlock
+      file="authkit-nextjs-server-component"
+      title="/app/home-page/page.jsx"
+    />
+
+  - | Client component
+
+    The `useAuth` hook is used to retrieve the current logged in user and their details.
+
+    <CodeBlock
+      file="authkit-nextjs-client-component"
+      title="/app/home-page/page.jsx"
+    />
+
+  ### Protected routes
+
+  For routes where a signed in user is mandatory, you can use the `ensureSignedIn` option.
+
+  - | Server component
+
+    <CodeBlock
+      file="authkit-nextjs-server-component-protected-route"
+      title="/app/protected/page.tsx"
+    />
+
+  - | Client component
+
+    <CodeBlock
+      file="authkit-nextjs-client-component-protected-route"
+      title="/app/protected/page.jsx"
+    />
+
+  ### Ending the session
+
+  Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's [Logout redirect](/user-management/sessions/configuring-sessions/logout-redirect) location, which is configured in the WorkOS dashboard.
+
+  <CodeBlock
+    file="get-authkit-url-nextjs-logout"
+    title="/app/home-page/page.jsx"
+  />
+
+- $ frontend="remix"
+
+  ### Callback route
+
+  When a user has authenticated via AuthKit, they will be redirected to your app's callback route. In your Remix app, [create a new route](https://remix.run/docs/en/main/discussion/routes) and add the following:
+
+  <CodeBlock file="callback-endpoint-remix" title="/routes/callback.ts" />
+
+  ### Initiate login route
+
+  We'll need an initiate login endpoint to direct users to sign in using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.
+
+  <CodeBlock file="initiate-login-endpoint-remix" title="/routes/login.ts" />
+
+  ### Access authentication data in your Remix application
+
+  We'll need to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. We'll do this by generating an AuthKit authorization URL server side and redirecting the user to it.
+
+  Use `authkitLoader` to configure AuthKit for your Remix application routes. You can choose to return custom data from your loader, like for instance the sign in and sign out URLs.
+
+  <CodeBlock file="authkit-remix-example-full" title="/app/routes/_index.jsx" />
+
+  ### Protected routes
+
+  For routes where a signed in user is mandatory, you can use the `ensureSignedIn` option in your loader.
+
+  <CodeBlock
+    file="authkit-remix-example-protected-route"
+    title="/app/protected/route.tsx"
+  />
+
+  ### Ending the session
+
+  Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's [Logout redirect](/user-management/sessions/configuring-sessions/logout-redirect) location, which is configured in the WorkOS dashboard.
+
+  <CodeBlock
+    file="authkit-remix-example-logout"
+    title="/app/routes/_index.jsx"
+  />
+
+- $ frontend="vanilla, react"
+
+  ### Set up the frontend
+
+  To demonstrate AuthKit, we only need a simple page with links to logging in and out.
+
+- $ frontend="vanilla"
+
+  <CodeBlock file="frontend-vanilla" title="index.html" />
+
+- $ frontend="react"
+
+  <CodeBlock file="frontend-react" title="App.js" />
+
+- $ frontend="vanilla, react"
+
+  Clicking the "Sign in" and "Sign out" links should invoke actions on our server, which we'll set up next.
+
+- $ backend="nodejs, ruby, php, go, python, java"
+
+  ### Add an initiate login endpoint
+
+  We'll need an initiate login endpoint to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. This endpoint should generate an AuthKit authorization URL server side and redirect the user to it.
+
+  You can use the optional state parameter to encode arbitrary information to help restore application `state` between redirects.
+
+- $ backend="nodejs"
+
+  For this guide we'll be using the `express` web server for Node. This guide won't cover how to set up an Express app, but you can find more information in the [Express documentation](https://expressjs.com/en/starter/installing.html).
+
+  <CodeBlock file="get-authkit-url-express" title="server.js" />
+
+- $ backend="ruby"
+
+  For this guide we'll be using the `sinatra` web server for Ruby. This guide won't cover how to set up a Sinatra app, but you can find more information in the [Sinatra documentation](https://sinatrarb.com/intro.html).
+
+  <CodeBlock file="get-authkit-url-sinatra" title="server.rb" />
+
+- $ backend="python"
+
+  For this guide we'll be using the `flask` web server for Python. This guide won't cover how to set up a Flask app, but you can find more information in the [Flask documentation](https://flask.palletsprojects.com/en/stable/).
+
+  <CodeBlock file="get-authkit-url-flask" title="server.py" />
+
+- $ backend="nodejs, ruby, python"
+
+  > WorkOS will redirect to your [Redirect URI](/glossary/redirect-uri) if there is an issue generating an authorization URL. Read our [API Reference](/reference) for more details.
+
+  ### Add a callback endpoint
+
+  Next, let’s add the callback endpoint (referenced in [Configure a redirect URI](/user-management/1-configure-your-project/configure-a-redirect-uri)) which will exchange the authorization code (valid for 10 minutes) for an authenticated User object.
+
+- $ backend="nodejs"
+
+  <CodeBlock file="callback-endpoint-express" title="server.js" />
+
+- $ backend="ruby"
+
+  <CodeBlock file="callback-endpoint-sinatra" title="server.rb" />
+
+- $ backend="python"
+
+  <CodeBlock file="callback-endpoint-flask" title="server.py" />
+
+- $ backend="nodejs, ruby, python"
+
+  ## (3) Handle the user session
+
+  Session management helper methods are included in our SDKs to make integration easy. For security reasons, sessions are automatically "sealed", meaning they are encrypted with a strong password.
+
+  ### Create a session password
+
+  The SDK requires you to set a strong password to encrypt cookies. This password must be 32 characters long. You can generate a secure password by using the [1Password generator](https://1password.com/password-generator/) or the `openssl` library via the command line:
+
+  ```bash title="Generate a strong password"
+  openssl rand -base64 32
+  ```
+
+  Then add it to the environment variables file.
+
+  ```plain title=".env"
+  WORKOS_API_KEY='sk_example_123456789'
+  WORKOS_CLIENT_ID='client_123456789'
+
+  # +diff-start
+  WORKOS_COOKIE_PASSWORD='<your password>'
+  # +diff-end
+  ```
+
+  ### Save the encrypted session
+
+  Next, use the SDK to authenticate the user and return a password protected session. The refresh token is considered sensitive as it can be used to re-authenticate, hence why the session is encrypted before storing it in a session cookie.
+
+- $ backend="nodejs"
+
+  <CodeBlock file="encrypt-session-express" title="server.js" />
+
+  ### Protected routes
+
+  Then, use middleware to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one.
+
+  <CodeBlock file="auth-middleware-express" title="server.js" />
+
+  Add the middleware to the route that should only be accessible to logged in users.
+
+  <CodeBlock file="protect-route-express" title="server.js" />
+
+  ### Ending the session
+
+  Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's [Logout redirect](/user-management/sessions/configuring-sessions/logout-redirect) location, which is configured in the WorkOS dashboard.
+
+  <CodeBlock file="log-out-express" title="server.js" />
+
+- $ backend="ruby"
+
+  <CodeBlock file="encrypt-session-sinatra" title="server.rb" />
+
+  ### Protected routes
+
+  Then, use a helper method to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one.
+
+  <CodeBlock file="auth-middleware-sinatra" title="server.rb" />
+
+  Call the helper method in the route that should only be accessible to logged in users.
+
+  <CodeBlock file="protect-route-sinatra" title="server.rb" />
+
+  ### Ending the session
+
+  Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's [Logout redirect](/user-management/sessions/configuring-sessions/logout-redirect) location, which is configured in the WorkOS dashboard.
+
+  <CodeBlock file="log-out-sinatra" title="server.rb" />
+
+- $ backend="python"
+
+  <CodeBlock file="encrypt-session-flask" title="server.py" />
+
+  ### Protected routes
+
+  Then, use a decorator to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one.
+
+  <CodeBlock file="auth-middleware-flask" title="server.py" />
+
+  Use the decorator in the route that should only be accessible to logged in users.
+
+  <CodeBlock file="protect-route-flask.trunk-ignore" title="server.py" />
+
+  ### Ending the session
+
+  Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's Logout redirect location, which is configured in the WorkOS dashboard.
+
+  <CodeBlock file="log-out-flask.trunk-ignore" title="server.py" />
+
+> If you haven't configured a [Logout redirect](/user-management/sessions/configuring-sessions/logout-redirect) in the WorkOS dashboard, users will see an error when logging out.
+
+### Validate the authentication flow
+
+Navigate to the authentication endpoint we created and sign up for an account. You can then sign in with the newly created credentials and see the user listed in the _Users_ section of the [WorkOS Dashboard](https://dashboard.workos.com).
+
+![Dashboard showing newly created user](https://images.workoscdn.com/images/54fa6e6c-4c6f-4959-9301-344aeb4eeac8.png?auto=format&fit=clip&q=80)

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

@@ -0,0 +1,60 @@
+---
+title: Invitations
+description: Easily add users to your application or as members of an organization.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/invitations.mdx
+---
+
+## Introduction
+
+Invitations are a way of adding a specific user to your application or as a member of an organization. They provide a flow for end-users to engage in collaboration that takes into consideration security and user choice.
+
+## Invitation flow
+
+Each invitation is for a specific email address to a specific organization. Invitations are for both new users and existing users.
+
+Each invitation is a two step process:
+
+- The inviter expresses intent for someone to join an organization.
+- The invitee chooses to join that organization.
+
+### Inviting new users to an organization
+
+If an invitation is created for an email address that does not yet exist, an email is sent to that user with a link to sign up for your application and join the organization.
+
+As part of signing up, they automatically join the organization. If a user is invited to multiple organizations, they only join the organization for which they clicked the invitation email for, indicating intent to join that specific organization.
+
+### Inviting existing users to an organization
+
+If an invitation is for an existing user, clicking the link in the email and signing in adds the user as a member to the organization. If the user is already signed in, you can use the invitation code to validate that the signed-in user is eligible to use the invitation, by querying the [Invitation API](/reference/user-management/invitation).
+
+This offers choice for the end-user so that they aren’t automatically added to organizations that may be attempting phishing attacks.
+
+## Application-wide invitations
+
+Invitations do not have to be specific to an organization. An invitation sent without specifying an organization is an invitation to join the application. This enables your existing users to help grow your application by inviting peers organically.
+
+When signup is disabled, users cannot register for a new account through [AuthKit](/user-management) or the [API](/reference/user-management/invitation). When a valid invitation code is present in the sign-in flow, registration is opened up both in AuthKit and the API so that a new user may sign up. This lets you model your application as a closed-registration invitation-only system.
+
+## Sending invitations
+
+Invitations can be sent programmatically by your application with the [Invitation API](/reference/user-management/invitation), or viewed and manually created in the [WorkOS Dashboard](https://dashboard.workos.com/). By default, WorkOS sends these emails, but you can also [send the emails yourself](/user-management/custom-emails).
+
+![Dashboard displaying a list of user invitations](https://images.workoscdn.com/images/18299a05-f824-410e-a17b-828fbe5826f1.png?auto=format&fit=clip&q=80)
+
+## Email address used to accept an invite
+
+Often, a user might want to accept their invitation using an email address that’s different from the one that the invitation was sent to.
+
+### Without organization membership
+
+When an invitation doesn’t include an organization to join, a user can accept the invitation using any email address.
+
+For example, an invitation sent to `user@example.com` can be used with `another-user@foo-corp.com` email address.
+
+### With organization membership
+
+For organization-specific invitations, there are different rules based on the email domain on the invitation.
+
+- **Consumer email domains**, such as Gmail or Yahoo: the invited user must sign up using exactly the same email address to which the invitation was sent.
+- **Corporate domains**: the user can sign up with any email address from the same domain as the email on the invitation. For example, an invitation sent to `user@foo-corp.com` can be accepted with `another-user@foo-corp.com`

package/.docs/organized/docs/user-management/invite-only-signup.mdx

@@ -0,0 +1,72 @@
+---
+title: Invite-only signup
+description: Modeling an invite-only application without a public signup page.
+showNextPage: false
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/invite-only-signup.mdx
+---
+
+## Introduction
+
+In this scenario, we outline the considerations, concepts, and best practices for modeling a closed-registration application in which users may only be added to the application via an invitation.
+
+## Goals & requirements
+
+Imagine a company that wishes to model an invite only application that requries an exclusive invite to access. The product is yet to launch, and as the initial release approaches they plan to seed memberships from a small subset of organizations and later allow existing users to invite new members from a quota.
+
+The requirements are as follows:
+
+- Signup should be unavailable to the general public.
+- An initial set of invites will be sent from a pre-existing mailing list.
+- Later, members should be able to invite other members, but only to a given quota.
+- Invites should be sent and accepted via email.
+
+## Invite-only model
+
+In order to implement a invite only structure, the application must account for the following:
+
+- AuthKit must not expose sign up controls to the general public.
+- Invites will be performed programmatically from a seed script.
+- Members can invite other members via an invite UI within the application.
+
+![Closed-registration authentication flow](https://images.workoscdn.com/images/4cb2c8f9-896d-4191-8b04-90d7bd908e6b.png?auto=format&fit=clip&q=80)[border=false]
+
+## Disabling signup
+
+AuthKit provides an out-of-the-box signup form which handles validation UX, makes the necessary WorkOS API calls and handles the end-to-end lifecycle of the invite flow (emailing of members, accepting of invites, assignment of members to organizations where appropriate).
+
+In this scenario, the application should not expose the signup flow to the general public. It can be disabled per environment by toggling the "Sign up" setting in the authentication section of the WorkOS dashboard.
+
+![Image of a modal in the WorkOS dashboard to disable sign-ups](https://images.workoscdn.com/images/76369560-2e4c-41bd-b3ba-1e7e1cf806e3.png?auto=format&fit=clip&q=80)[border=false]
+
+## Inviting users
+
+User invitations can be issued in one of two ways:
+
+- Via the WorkOS dashboard.
+- Programmatically via the WorkOS SDK.
+
+The simplest way to get started is via the WorkOS dashboard. Invites can be created by navigating to "Invites" tab in the "Users" section of the dashboard.
+
+![Image of a modal in the WorkOS dashboard to invite new users](https://images.workoscdn.com/images/94103735-c85e-43e2-aee1-3a46c33bf2a2.png?auto=format&fit=clip&q=80)[border=false]
+
+This is helpful in the early stages of product development where there may be a small number of potential users and the product is not yet mature enough to warrant development time spent implementing custom invitation controls, or when dealing with support requests from users who are having difficulty.
+
+## Programmatic invitations
+
+Manually issuing invitations from the dashboard is not scalable nor always feasible when needing to issue a large number of invites, or if organic sign up growth is desired without a support team. In this case using the WorkOS API to perform and manage invitations is preferred.
+
+### Seeding initial users from a script
+
+Typically, an application will implement a "seed" script which will be run once to issue a set of invites to a pre-existing mailing list. This can be done by using the WorkOS API to create an invite for each email address in the list.
+
+## Inviting users within the application
+
+Custom invitation controls can be implemented within the application to allow members to invite other members. This generally requires adding a form to the UI to collect the email address of the user to invite alongside a button to trigger the API call. Additionally, a count of the number of invites a user has made might be stored and checked against a quota to ensure they don't exceed the number of invites they are allowed to send.
+
+A call can then be made to [the WorkOS API](/reference/user-management/invitation/send) by supplying the target users email address as well as the ID of the originating organization. The invited user can then accept this invite via email and move through the steps to gain access to the application.
+
+## Summary
+
+This scenario covers some high-level considerations when thinking about closed-registration application. By using AuthKit, the WorkOS API, and the dashboard it's possible to limit signup and implement an invite flow within your application.
+
+In cases where the signup restriction is temporary, signup in AuthKit can be easily re-enabled via a setting in the WorkOS dashboard.