@workos/mcp-docs-server 0.1.0

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

@@ -0,0 +1,101 @@
+---
+title: Sessions
+description: Learn more about integrating sessions.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/sessions.mdx
+---
+
+## Introduction
+
+When a user signs in to your app, a user session is created. Along with the [User object](reference/user-management/user), a successful authentication response will include an access token and refresh token. Your application can use these tokens to ensure that the user’s session is still active.
+
+Each user session can be viewed from within the WorkOS dashboard:
+
+![Sessions Detail UI](https://images.workoscdn.com/images/295ded3e-7e8f-4322-bcc0-95db1cfc255b.png?auto=format&fit=clip&q=80)
+
+Navigate to _Users_ and select a user. Then, switch to _Sessions_ tab and click on a user session to get more information.
+
+## Integrating Sessions
+
+Successful authentication responses will include both an access token and a refresh token. The access token should be stored as a secure cookie in the user’s browser and should be validated by the backend on each request. The refresh token should either be stored in a secure cookie or persisted on your backend. Once the access token has expired, a new one can be obtained using the refresh token.
+
+![Sessions Diagram](https://images.workoscdn.com/images/aa420ffa-3b8c-462c-992b-b53e458dd916.png?auto=format&fit=clip&q=80)[border=false]
+
+### Access Token
+
+If you’re using our [Next SDK](https://www.npmjs.com/package/@workos-inc/authkit-nextjs) or [Remix SDK](https://github.com/workos/authkit-remix), all the work of validating access tokens and refreshing expired tokens is handled for you (more framework support coming soon). Read on for details about how token handling works.
+
+The access token is a JSON Web Token (JWT), which should be validated on each request using a library like jose. The [signing JWKS](/reference/user-management/session-tokens/jwks) can be found at `http://api.workos.com/sso/jwks/<clientId>`. The JWT includes the following claims:
+
+- `sub`: the WorkOS user id
+- `sid`: the session ID (used for signing out)
+- `iss`: `https://api.workos.com/` (will be your custom auth domain if configured)
+- `org_id`: the organization that was selected at sign-in time (if applicable)
+- `role`: the role of the selected organization membership (only applicable if an organization is selected)
+- `permissions`: the permissions assigned to the role (if applicable)
+- `exp`: the standard `expires_at` claim (the token should not be trusted after this time)
+- `iat`: the standard `issued_at` claim
+
+### Refresh Token
+
+Refresh tokens should be persisted on the backend in, for instance, a database, cache, or secure http-only cookie. A new access token can be obtained by using the [authenticate with refresh token](/reference/user-management/authentication/refresh-token) endpoint. If the session is still active, a new access token and refresh token will be returned. Refresh tokens are single use, so be sure to replace the old refresh token with the newly generated one.
+
+### Switching Organizations
+
+Refresh tokens can be used to obtain a new access token for a different organization by passing the `organization_id` parameter to the [authenticate with refresh token](/reference/user-management/authentication/refresh-token) endpoint. If the session for the refresh token is authorized to access the organization, then the `org_id` will be set to the given organization, along with the `role` and `permissions` claims matching the user's membership in that organization.
+
+If the user is not authorized for the organization, then an appropriate [authentication error](/reference/user-management/authentication-errors) will be returned and the user will need to authenticate. Applications using [AuthKit](/user-management/authkit) can use the [Get Authorization URL](/reference/user-management/authentication/get-authorization-url) and the `organization_id` parameter to initiate the authentication flow specifically for the organization.
+
+### Signing Out
+
+When a user signs out of your app, the following steps should occur:
+
+- Get the session id (`sid` claim) out of the access token.
+- Delete the user’s app session.
+- Redirect the user’s browser to [logout endpoint](/reference/user-management/logout) endpoint (this will ensure the user’s session ends at WorkOS).
+- The user will be redirected back to the URL configured as your _App homepage URL_
+
+#### Example
+
+```javascript
+// extract sessionId from access token
+const sessionId = jose.decodeJwt(session.accessToken).sid;
+
+// delete app session cookie
+cookies().delete('my-app-session');
+
+// redirect to logout endpoint
+// (the user will be redirected to your app homepage url
+//  after the logout completes)
+redirect(workos.userManagement.getLogoutUrl({ sessionId }));
+```
+
+## Configuring Sessions
+
+Using the WorkOS dashboard you can configure how Sessions work in your integration. You’ll find the settings in the _Authentication_ section.
+
+![Session Configuration UI](https://images.workoscdn.com/images/158987a3-127c-4bcd-a3ac-53b1be0abd8a.png?auto=format&fit=clip&q=50)
+
+- **Maximum session length:** The session will expire after this length of time. Once expired the user will need to sign in again.
+- **Access token duration:** Your backend can verify the access token on each request (see the [Integrating Sessions](user-management/sessions/integrating-sessions) section above). It’s recommended to keep the access token duration short so that changes in the session are quickly reflected in your app.
+- **Inactivity timeout:** The session ends if a refresh has not occurred in this length of time. The user will need to sign in again.
+
+Additionally, make sure to review your settings in the _Redirect_ section:
+
+### Logout redirect
+
+![Logout redirect settings](https://images.workoscdn.com/images/8605a0d5-8968-409e-90af-cca4e56247ed.png?auto=format&fit=clip&q=80)
+
+Make sure to set a default Logout URI, which will be the location users will be redirected to after their session has been ended. Non-default Logout URIs can be used as values to the `return_to` parameter of the [Logout API](/reference/user-management/logout/get-logout-url) in order to dynamically choose the final logout redirect location.
+
+#### Wildcards
+
+The `*` symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules in order to properly function.
+
+- Wildcard Logout URIs can only be created in staging environments.
+- The protocol of the URL **must** be either `http:` or `https:`. For example, `com.example.app://*.example.com` will not work.
+- The wildcard **must** be located in a subdomain within the hostname component. For example, `http://*.com` will not work.
+- The wildcard **must** be located in the subdomain which is furthest from the root domain. For example, `https://sub.*.example.com` will not work.
+- The URL **must not** contain more than one wildcard. For example, `https://*.*.example.com` will not work.
+- A wildcard character **may** be prefixed and/or suffixed with additional valid hostname characters. For example, `https://prefix-*-suffix.example.com` will work.
+- A URL with a valid wildcard **will not** match a URL more than one subdomain level in place of the wildcard. For example, `https://*.example.com` will not work with `https://sub1.sub2.example.com`.

package/.docs/organized/docs/user-management/social-login.mdx

@@ -0,0 +1,34 @@
+---
+title: Social Login
+description: Quickly and easily integrate with social OAuth providers.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/social-login.mdx
+---
+
+## Introduction
+
+Social Login allows users to sign in or sign up using their existing credentials with OAuth providers such as Google, Microsoft, GitHub, and Apple.
+
+## Getting started
+
+AuthKit will make the necessary API calls and route users through OAuth providers automatically during the authentication flow, though the relevant providers must first be configured and enabled.
+
+### (1) Configure OAuth providers
+
+Configuration can be supplied via the _Authentication_ section of the [WorkOS Dashboard](https://dashboard.workos.com). WorkOS provides integration guides for common providers such as [Google](/integrations/google-oauth), [Microsoft](/integrations/microsoft-oauth), [GitHub](/integrations/github-oauth), [Apple](/integrations/apple), [GitLab](/integrations/gitlab-oauth), [LinkedIn](/integrations/linkedin-oauth), and [Slack](/integrations/slack-oauth).
+
+![Dashboard configure OAuth settings](https://images.workoscdn.com/images/037ede88-0b7a-4e26-9ede-441a25ce584c.png?auto=format&fit=clip&q=80)
+
+### (2) Enable OAuth providers
+
+After a provider has been configured and enabled, it will appear as a sign in option on the AuthKit authentication page.
+
+![AuthKit sign in page with social providers highlighted](https://images.workoscdn.com/images/f743cf4f-a32c-464b-94a4-db9f5c146773.png?auto=format&fit=clip&q=80)
+
+---
+
+## Integrating via the API
+
+If you’d prefer to build and manage your own authentication UI, you can do so via the User Management [Authentication API](/reference/user-management/authentication).
+
+Examples of building custom UI are also [available on GitHub](https://github.com/workos/authkit).

package/.docs/organized/docs/user-management/sso-with-contractors.mdx

@@ -0,0 +1,85 @@
+---
+title: SSO with contractors
+description: Enforcing organization SSO access with external contractors.
+showNextPage: true
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/user-management/sso-with-contractors.mdx
+---
+
+## Introduction
+
+In this scenario, we outline the considerations, concepts, and best practices for configuring and enforcing SSO sign-in for all members of an organization, we'll also cover how to enforce these same constraints on external contractors who may need access to company resources but are not permanent members.
+
+## Goals & requirements
+
+The application should be available to logged in users only. Each user is typically assigned to a single organization and will be able to collaborate with other users within that organization.
+
+- The majority of users collaborate within the same organization.
+- Permanent members of the organization use an email address that matches the organization's domain.
+- Organization members are required to authenticate using SSO.
+- External contractors and collaborators are also required to authenticate using SSO.
+
+![Diagram of AnalyticsOS auth flow for users and contractors](https://images.workoscdn.com/images/b9752155-4f5d-4702-890d-c64caa54005e.png?auto=format&fit=clip&q=80)[border=false]
+
+## Integrating SSO
+
+Adding SSO to your application is a straightforward process when using AuthKit, and can mostly be done via the WorkOS dashboard. Steps include:
+
+(1) Add a new SSO connection to an organization in the dashboard
+
+(2) Configure a callback endpoint in your application
+
+(3) Add your endpoint URL as a sign-in callback in the WorkOS dashboard
+
+(4) Handle the user session and grant access to the application
+
+### Enforcing SSO authentication
+
+With an active SSO connection established, it's now possible to enable it as an authentication method in the WorkOS Dashboard. This can be achieved by visiting the authentication settings view for the environment and enabling Single Sign-On.
+
+![Enable SSO in the WorkOS dashboard](https://images.workoscdn.com/images/feb25320-d75c-47bf-ae63-ae7a99a84afb.png?auto=format&fit=clip&q=80)[border=false]
+
+This will allow users to sign-in with AuthKit using SSO, but will not enforce it as a requirement. In order to do so, we'll need to configure an authentication policy for the organization.
+
+### SSO authentication flow
+
+When the user logs in, they will move through the following flow:
+
+(1) User clicks “Sign in” button
+
+(2) User is redirected to AuthKit, where they sign via SSO
+
+(3) User is redirected from AuthKit to the redirect URI configured in the WorkOS dashboard
+
+(4) User is authenticated via code presented in the `redirect_uri`
+
+(5) Access is provisioned by the application
+
+More in-depth information on configuration can be found in the [Single Sign-On section](/user-management/sso), with AuthKit implementation guidance available in the [Quick Start guide](/user-management).
+
+## Understanding authentication policies
+
+An authentication policy is a way to enforce specific authentication methods during sign-in. They typically apply to all users attempting to access the organization.
+
+There are several approaches to enforcing SSO within an organization, including domain verification and enforcing specific policies on those inside and outside of the organization based on their attached email domain, but for the purposes of simplicity we will simply cover a blanket authentication policy which applies to all users attempting to sign-in, regardless of verified domain existence.
+
+An authentication policy allows the organization to:
+
+- Enforce SSO be used by all users accessing the organization
+- Enforce an MFA requirement for all users accessing the organization
+
+## Adding an authentication policy
+
+Authentication policies can be applied in the organization settings view of the WorkOS Dashboard.
+
+![Applying authentication policy in the WorkOS dashboard](https://images.workoscdn.com/images/22fc71c4-1565-45e4-a148-d96de148cdd4.png?auto=format&fit=clip&q=80)[border=false]
+
+After adding SSO enforcement to the policy, all users will be required to sign-in using SSO. This will apply to all users, including external contractors. For this to function with external contractors, they will need to be added to the organization's IdP.
+
+For cases where external contractors can not be added to the organization's IdP, an MFA requirement can be set as an enforcement fallback. This is sometimes a reasonable compromise if many contractors rotate in out of the organization.
+
+## Summary
+
+The organization should now be set up and to both accept SSO connections and enforce their use for all users, including external contractors. In the contractor case they will require adding to the organizations IdP or otherwise fallback to using MFA.
+
+This scenario did not cover the full range of access constraints that can be applied to an organization following domain verification, for more information on this topic see the Access Constraints section of the documentation.

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

@@ -0,0 +1,96 @@
+---
+title: Single Sign-On
+description: >-
+  Facilitate greater security, easier account management, and accelerated
+  application onboarding and adoption.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/sso.mdx
+---
+
+## Introduction
+
+Single Sign-On is the most frequently asked for requirement by organizations looking to adopt new SaaS applications. SSO enables authentication via an organization’s [identity provider (IdP)](/glossary/idp).
+
+This service is compatible with any IdP and supports both the [SAML](/glossary/saml) and [OIDC](/glossary/oidc) protocols. It’s modeled to meet the [OAuth 2.0](/glossary/oauth-2-0) framework specification, abstracting away the underlying authentication handshakes between different IdPs.
+
+## Getting started
+
+AuthKit greatly simplifies the process of integrating SSO into your application. AuthKit will make the necessary API calls automatically and handle the routing of SSO users when their account is associated with an existing SSO connection.
+
+## (1) Enable SSO
+
+Navigate to the _Authentication_ settings section in the [WorkOS Dashboard](https://dashboard.workos.com/) and enable Single Sign-On.
+
+![Dashboard demonstrating how to enable Single Sign-On](https://images.workoscdn.com/images/09c9b3c5-833e-4fe0-985b-f5b1934e4284.png?auto=format&fit=clip&q=80)
+
+AuthKit will now automatically detect when a user is attempting to sign in via SSO and redirect them to the appropriate IdP.
+
+## (2) Test with the Test Identity Provider
+
+To confirm your Single Sign-On integration works correctly you can use the Test Identity Provider to simulate login flows end-to-end. Your staging environment includes a default Test Organization and active SSO connection configured with the Test Identity Provider.
+
+![WorkOS Test Identity Provider](https://images.workoscdn.com/images/7b7407d7-dcc7-4fd4-859f-4ee4214d69c2.png?auto=format&fit=clip&q=80)
+
+### Getting started
+
+Log into the [WorkOS Dashboard](https://dashboard.workos.com/) and navigate to the _Test SSO_ page to get started with the Test IdP. This page outlines a number of different SSO scenarios you can follow and provides all the necessary information to complete the tests.
+
+![Test SSO WorkOs Dashboard](https://images.workoscdn.com/images/7b7407d7-dcc7-4fd4-859f-4ee4214d69c2.png?auto=format&fit=clip&q=80)
+
+### Service provider-initiated SSO
+
+This case is likely the first [login flow](/sso/login-flows/sp-initiated-sso) you would test when implementing SSO in your app. The test simulates users initiating authentication from your sign-in page. In this scenario, the user enters their email in your app, gets redirected to the identity provider, and then is redirected back to your application.
+
+### Identity provider-initiated SSO
+
+This test simulates users initiating authentication from their identity provider. It is a common [login flow](/sso/login-flows/idp-initiated-sso) that developers forget to consider. In the scenario, users log in to the identity provider directly, select your application from their list of SSO-enabled apps, and are redirected to your application upon successful authentication.
+
+### Guest email domain
+
+This test simulates users authenticating with an email domain different from the verified domain of the test organization, `example.com`. A relevant scenario is authenticating freelance users, whose email domain is not owned by the company.
+
+### Error response
+
+This test simulates a generic [error response](/reference/sso/get-authorization-url/error-codes) from the user’s identity provider. In this scenario, SSO authentication has failed for the user. Below is an example of the error-related parameters passed to the [redirect URI](/sso/redirect-uris) in your application.
+
+---
+
+## (3) Test with other identity providers
+
+Test Identity Provider saves time by providing an out of the box experience compared to the configuration process that someone using a real identity provider would have to go through to enable Single Sign-On for your app.
+
+If your integration works with the Test Identity Provider, you can be sure it will work with other identity providers. However, it may be helpful to also learn about the setup process that your customers will go through on their side, which varies depending on a specific identity provider.
+
+### Create an organization
+
+To get started, you will need to [create an organization](https://dashboard.workos.com/organizations) in the WorkOS Dashboard. Organizations in WorkOS represent your customer, so by creating an organization, you can test your SSO connection the way your customers will experience it.
+
+![Create an organization dialog](https://images.workoscdn.com/images/2ef3565c-526a-42e6-9830-622e83b67ee5.png?auto=format&fit=clip&q=80)
+
+### Create a connection
+
+Go to the organization you created and click _Invite admin_. Select _Single Sign-On_ from the list of features. In the next step, enter an email address to send the setup link to, or click _Copy setup link_.
+
+The setup link goes to Admin Portal, where your customers get the exact instructions for every step they need to take to enable Single Sign-On with your app.
+
+> You can also integrate [Admin Portal](/admin-portal) directly into your app to enable self-serve setup of Single Sign-On and other enterprise features for your users.
+
+![Invite an admin dialog](https://images.workoscdn.com/images/b9ab80fc-606a-417c-bade-3483ef48c2ae.png?auto=format&fit=clip&q=80)
+
+### Follow the Admin Portal instructions
+
+To complete the integration, you’ll have to also create an account with the identity provider you want to test with. After you have signed up with an identity provider of your choice, follow the corresponding Admin Portal instructions from the setup link. Once done, you can start testing your SSO integration with that identity provider.
+
+![Admin Portal setup instructions](https://images.workoscdn.com/images/0ee15c3d-5356-4f41-a26a-440f95355b28.png?auto=format&fit=clip&q=80)
+
+The setup instructions you’ve seen in the Admin Portal are also available directly in the docs if you want to create a connection manually:
+
+<ProviderCards.SsoIntegration />
+
+---
+
+## Integrating via the API
+
+If you’d prefer to build and manage your own authentication UI, you can do so via the User Management [Authentication API](/reference/user-management/authentication).
+
+Examples of building custom UI are also [available on GitHub](https://github.com/workos/authkit).

package/.docs/organized/docs/user-management/users-organizations.mdx

@@ -0,0 +1,91 @@
+---
+title: Users and Organizations
+description: Flexible application modeling with user and membership features.
+showNextPage: true
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/user-management/users-organizations.mdx
+---
+
+## Users
+
+The [User object](/reference/user-management/user) represents an identity that has access or owns artifacts in your application. A User object may not uniquely identify an individual person, since a person may present themselves as having multiple identities in the same system.
+
+What uniquely identifies a user is their **email address**, since having access to that email inbox ultimately gives access to all accounts based on that address.
+
+### Authentication methods
+
+There may be multiple authentication methods on a single user object, such as [Email + Password](/user-management/email-password) or [OAuth](/user-management/social-login). A user can sign in with any of the authentication methods associated with them, as long as you have enabled those authentication methods in the WorkOS Dashboard.
+
+<UserManagementDiagrams.AuthenticationMethods />
+
+### Identity linking
+
+Because a user is uniquely identified by their email address, you won’t have users with duplicate email addresses. WorkOS handles [identity linking](/user-management/identity-linking) automatically.
+
+### Email verification
+
+All users will go through an initial [email verification process](/user-management/email-verification) by default.
+
+This applies to all authentication methods, including OAuth and SSO. This unifying interface simplifies how your application considers the authenticity of your users.
+
+### Domain verification
+
+If a user’s email domain matches a verified organization domain, they will [automatically be considered verified](/user-management/domain-verification) and will not need to go through the email verification flow.
+
+---
+
+## Organizations
+
+Organizations represent both a collection of users that your customer’s IT admin has control over and a workspace within which members collaborate. Organizations are a first-class concept in WorkOS and support a suite of features around organizational management. There is no limit to the number of organizations you can create in WorkOS.
+
+### Organization memberships
+
+An organization contains users as members. Organization membership allows you to model organizations as "workspaces" and user’s access to them with memberships.
+
+WorkOS organization memberships are designed to be flexible, and support any B2B app model. For example:
+
+<UserManagementDiagrams.UserToOrganizationRelationships />
+
+- **Multiple Workspaces:** A self-serve productivity app, like Figma, where each user can be in any number of organizations, can create their own workspace and join any number of other workspaces.
+- **Single Workspace:** An app that has no collaboration outside a customer’s company, like an employee survey tool, where each user is in exactly one organization.
+
+While these are two distinct models, your choice may depend on your go-to-market strategy, which may change over time. **WorkOS User Management supports both**.
+
+### Organization access
+
+It’s common for users to create resources in B2B applications. You can use the organization as a container for these resources, so that access is dependent on a user’s access to the organization.
+
+This means when a user leaves an organization and is no longer a member, the data remains with the organization and not the user. Organizations provide the level of data ownership that B2B applications structure around.
+
+While organization membership conveys the most basic form of access, you can attach more granular role information per member within your own application’s database.
+
+### Organization roles
+
+In addition to the [environment-level roles](/user-management/roles-and-permissions/configure-roles-and-permissions), organizations can define their own custom roles, which are assignable only within the context of the organization. Refer to the [organization roles documentation](/user-management/roles-and-permissions/organization-roles) for more details.
+
+### Membership management
+
+If your application uses a soft-delete model, you can utilize the extended organization membership lifecycle. Organization memberships have three possible statuses:
+
+- `pending`, when a user is invited to an organization
+- `active`, when a user is added as an organization member or accepts an invitation
+- `inactive`, when an organization membership is deactivated
+
+For soft-delete use cases, we also provide deactivation and reactivation APIs:
+
+- [Deactivating an organization membership](/reference/user-management/organization-membership/deactivate) sets its status to `inactive` and revokes all active [sessions](/user-management/sessions). Note `pending` memberships cannot be deactivated and should be deleted using the [deleting membership API](/reference/user-management/organization-membership/delete) instead.
+- [Reactivating an organization membership](/reference/user-management/organization-membership/reactivate) sets its status to `active` and retains the role attached to the organization membership prior to deactivation. This role can be updated using the [update organization membership API](/reference/user-management/organization-membership/update). Note `pending` memberships cannot be reactivated. For this the user should go through the [invitation acceptance flow](/user-management/invitations) instead. If invitations are not needed, the organization membership can be [created as active directly](/reference/user-management/organization-membership/create).
+
+If your application uses a hard-delete model, you may use organization memberships without deactivation/reactivation by [deleting memberships](/reference/user-management/organization-membership/delete) for users who should no longer have access to an organization.
+
+### When to use deletion vs. deactivation
+
+Hard deletion is preferred if the app has no need to "remember" the membership. For example, when members operate solely on customer data and have no data of their own. When a member of the organization is gone, there's no need to keep around their membership data. An app in this case may even want to entirely [delete the User](/reference/user-management/user/delete) once the membership is deleted.
+
+Deactivation may be preferred in cases where a member retains some data after leaving the organization, for example: messages, documents, or other data which reference that member. It also allows for building a user interface to list former members, perhaps with the option to reactivate them.
+
+### Automated memberships
+
+Beyond manually adding or removing users to and from organizations as members, users can be automatically [Just-in-Time (JIT) provisioned](/user-management/jit-provisioning) into an organization if their email address matches one of the organization's [verified domains](/user-management/domain-verification). This allows customers to quickly onboard teammates.
+
+Users can also [invite individuals to organizations](/user-management/invitations), regardless of their email domain. This is handy for contractors within a company, or a collection of people without a shared domain.

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

@@ -0,0 +1,190 @@
+---
+title: WorkOS Widgets
+description: Learn how to integrate WorkOS Widgets in your app.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/widgets.mdx
+---
+
+## Introduction
+
+WorkOS Widgets are React components that provide complete functionality for common enterprise app workflows, for example a Users Management Widget that provides a UI for inviting, removing and editing users.
+
+This guide will cover how to add a widget to your app, configure CORS, and supply an authorization token for the widget.
+
+## Integrating
+
+First, install the `@workos-inc/widgets` package from the npm registry, along with its peer dependencies:
+
+```bash title="Install packages"
+npm install @workos-inc/widgets @radix-ui/themes @tanstack/react-query
+```
+
+### CORS configuration
+
+Because WorkOS widgets issue client-side requests to WorkOS, it is necessary to configure your site as an allowed web origin. Adding this in the [Authentication section of the dashboard](https://dashboard.workos.com/) will prevent CORS issues when using the widget.
+
+![CORS configuration](https://images.workoscdn.com/images/deb27664-e2e1-4c3b-afa1-e8ba2578c77c.png?auto=format&fit=clip&q=50)
+
+### Tokens
+
+Widgets must be supplied with an authorization token. The token can be acquired in one of two ways:
+
+- If you are using the `authkit-js` or `authkit-react` libraries, you can use the provided access token.
+- If you use one of our backend SDKs, use the "get token" method in the SDK to request a token with the appropriate scope for the widget you want to use. Widget tokens expire after one hour.
+
+<CodeBlock file="widgets-get-token" />
+
+> New WorkOS accounts are created with an "Admin" role that has all Widget permissions assigned. Existing accounts will need to assign the proper permissions to a role. This can be done on the "Roles" page of the WorkOS Dashboard. See the [Roles and Permissions guide](/user-management/roles-and-permissions) for more information.
+
+To successfully generate a token, the user must be assigned a role with the correct permissions for the widget.
+
+## Styling
+
+### Radix Themes
+
+WorkOS Widgets are powered by Radix Themes, which are styled out-of-the-box when you import its CSS in your app. You'll also need to import an additional CSS file from the WorkOS Widgets package to get everything looking just right.
+
+<CodeBlock language="js" file="widgets-radix-import" />
+
+You can customize Widgets by passing a `theme` prop to `WorkOSWidgets`. This prop accepts an object with the same options as [Radix themes](https://www.radix-ui.com/themes/docs/components/theme#api-reference).
+
+<CodeBlock
+  title="Theme customization"
+  file="theme-customization"
+  language="js"
+/>
+
+### CSS
+
+If you choose not to use the theming capabilities in Radix Themes, you can style Widgets using CSS. We recommend starting with the `layout.css` stylesheet from Radix Themes, as well as the `base.css` stylesheet from WorkOS Widgets. These styles provide a base level of functional styling without opinionated design choices.
+
+<CodeBlock language="js" file="widgets-css-imports" />
+
+Individual elements in Radix themes are accessible via CSS class selectors prefixed with `woswidgets-`. For example, you can add your own button styles by selecting the `woswidgets-button` class.
+
+<CodeBlock
+  title="CSS customization"
+  file="widgets-css-customization"
+  language="css"
+/>
+
+## User Management
+
+![Users Management screenshot](https://images.workoscdn.com/images/20f235c5-c888-48f5-90aa-87ec9189483a.png?auto=format&fit=clip&q=50)
+
+The `<UsersManagement />` widget allows an organization admin to manage the members in an org. Admins can invite new users, remove users, and change roles all within the widget.
+
+In order to use the User Management widget, a user must have a role that has the `widgets:users-table:manage` permission.
+
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-usersmanagement-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-usersmanagement-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+
+## Organization Switcher
+
+The `<OrganizationSwitcher />` widget allows an organization admin to switch between organizations. There are no special permissions required to use this widget as users can switch between organizations they have access to. If an organization requires SSO or MFA, the user will be redirected to reauthorize with the new organization.
+
+![Organization Switcher screenshot](https://images.workoscdn.com/images/e22cad7a-f11a-4f47-8cc7-fb015a22114f.png?auto=format&fit=clip&q=80)
+
+### Switching Organizations
+
+There are multiple ways to integrate with the Organization Switcher widget depending on your library choice. If you are using either the `authkit-js` or `authkit-react` libraries, you can use the `useAuth` hook to get the current organization and pass it to the widget.
+
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-organization-switcher-authkit-react"
+    title="React Library"
+  />
+</CodeBlock>
+
+If you are using one of the backend SDKs, you can build the organization switcher action in the backend and pass it in as a prop to the widget to be called when the user attempts to switch organizations. See the [Switching Organizations](/user-management/sessions/integrating-sessions/switching-organizations) guide for more information to set up the backend actions. This can then be passed in as a prop to the widget.
+
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-organization-switcher-backend"
+    title="Backend Handling"
+  />
+</CodeBlock>
+
+### Creating Organizations
+
+The widget accepts children components that can be used to either redirect the user to create an organization or to show a modal with a form to create an organization. You can use this to integrate with your existing organization creation flow that uses the WorkOS APIs to create organizations.
+
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-organization-switcher-create-authkit-react"
+    title="Create Organization"
+  />
+</CodeBlock>
+
+## User Profile
+
+The `<UserProfile />` widget allows users to view and manage their personal information.
+Users can see their profile details and edit their display name.
+This widget provides a simple, user-friendly interface for basic profile management.
+
+No special permissions are required to use this widget.
+
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-userprofile-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-userprofile-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+
+## User Sessions
+
+The `<UserSessions />` widget provides users with visibility into their active sessions across different devices and browsers. Users can view session details and sign out of individual sessions as needed. No special permissions are required to use this widget.
+
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-usersessions-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-usersessions-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+
+## User Security
+
+The `<UserSecurity />` widget enables users to control their security settings. With this widget, users can:
+
+- Set or change their password
+- Configure and reset Multi-Factor Authentication
+
+No special permissions are required to use this widget.
+
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-usersecurity-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-usersecurity-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>

package/.docs/organized/docs/vault/_navigation.mdx

@@ -0,0 +1,14 @@
+---
+title: Vault
+links:
+  - title: Getting Started
+    links:
+      - title: Overview
+        url: /vault
+      - title: Quick Start
+        url: /vault/quick-start
+      - title: Key Context
+        url: /vault/key-context
+originalPath: .tmp-workos-clone/packages/docs/content/vault/_navigation.mdx
+---
+