@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/user-management/modeling-your-app.mdx

@@ -0,0 +1,149 @@
+---
+title: Modeling Your App
+description: Learn how to architect your WorkOS integration
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/modeling-your-app.mdx
+---
+
+## Introduction
+
+WorkOS has a wide suite of products to solve your business needs. This guide explains some of the common choices when it comes to modeling your integration.
+
+WorkOS is designed to support a wide array of use cases and architectural scenarios, from simple business-to-consumer (B2C) user authentication to complex business-to-business (B2B) architectures with multiple organizations and authentication policy enforcement.
+
+Features are designed to grow with you, allowing you get started easily and expand your security options as you onboard larger and larger enterprise customers.
+
+Whether you are looking to add the initial authentication piece to a new application, or exploring migration from an existing vendor, you may find yourself asking:
+
+- Does WorkOS fit into my existing architecture?
+- Can I start small and later adopt more features?
+- I have very specific requirements, can I still use WorkOS?
+
+In most cases the answer is yes, and the aim of this guide is to help you understand how. We’ll cover the terminology used in this space, describe some common B2C and B2B flows, and finally demonstrate some scenarios that explain how everything fits together.
+
+## Understanding the authentication flow
+
+Supporting Email + Password, Single Sign-On, OAuth, Magic Auth, and other authentication concerns on your own is a complex task. You'd need to understand the authentication process, as well as model your applications sign-in and signup user interfaces to account for and handle all possible routes, error states and edges cases.
+
+There are three main ways to add WorkOS authentication to your application:
+
+### AuthKit
+
+A [hosted login solution](/user-management/authkit) that provides a customizable UI and supports a wide range of authentication methods.
+
+### Custom AuthKit UI
+
+If you prefer to craft your own UI in your own stack, AuthKit can be integrated with the [User Management API](/reference/user-management).
+
+### Standalone Single Sign-On (SSO)
+
+For applications that are only interested in [SSO capabilities](/reference/sso).
+
+In the majority of cases we recommend using the hosted AuthKit solution.
+
+![AuthKit authentication flow diagram](https://images.workoscdn.com/images/12d849cf-c710-493d-a189-48264d1c3ed7.png?auto=format&fit=clip&q=80)[border=false]
+
+On successful completion, AuthKit will return an authentication code to your application via your specified redirect URI, this is exchanged for the user object and used to create a session.
+
+See the [Quick Start guide](/user-management) for more information on how to implement this.
+
+## Authentication methods
+
+Prior to building your integration, it is useful to think about which authentication methods are part of your requirements. Typical consumer authentication methods include the following:
+
+### Email + Password
+
+The most common method of authentication, users sign up or sign in to your app with email and password. This method is enabled by default.
+
+### OAuth
+
+OAuth, also known as Social Login, is when a user logs in with an account belonging to a different service. Examples include logging in with your Google, Microsoft or GitHub account instead of making a new account with your app. These authentication methods can be configured from the WorkOS dashboard.
+
+### Magic Auth
+
+Also known as Passwordless, Magic Auth authentication works by emailing the user a unique, one-time-use 6 digit code which they then use to authenticate.
+
+A similar technique is Magic Link, where the user can log in by clicking a link emailed to them. This method has proven to be unreliable as IT teams often employ security measures that scan user emails and programmatically click any links found in the email, invalidating the Magic Links. As such, WorkOS has deprecated Magic Links in favour of Magic Auth.
+
+### SSO
+
+The favored authentication method by enterprise sized companies, SSO allows an organization's users to sign in with a single ID to related, yet independent software systems.
+
+The WorkOS User Management APIs make the above easy to implement using your own UI, or you can use AuthKit for a fully hosted experience.
+
+## Single-tenant and multi-tenant models
+
+You might encounter the concepts of single-tenant and multi-tenant when discussing an application’s authentication model. Single-tenant and multi-tenant architectures offer different approaches to managing resources and data in software applications, especially in cloud services or Software as a Service (SaaS) environments.
+
+![Diagram of single and multi-tenant models](https://images.workoscdn.com/images/48ef829e-6758-4606-a696-7963beb803b2.png?auto=format&fit=clip&q=80)[border=false]
+
+### Single-tenant
+
+In the context of authentication and authorization, single-tenant refers to a software architecture where a separate instance of the software is set up for each client on separate servers or virtual machines.
+
+Each organization is paired with its own instance of both the application and the underlying database. This approach offers full data isolation between customers, but comes at the cost of being more resource-intensive and costly. Each client’s setup may require separate maintenance, updates, and support.
+
+### Multi-tenant
+
+Multi-tenant refers to a software architecture where a single instance of the software serves multiple customer organizations, known as tenants.
+
+Each tenant's data is isolated and remains invisible to other tenants because the software is designed to securely handle this data across all tenants.
+
+In the context of WorkOS, a multi-tenant application could be accomplished by the use of [Organizations](/reference/organization) and [Organization Memberships](/reference/user-management/organization-membership) to ensure that end-users only have access to the data they are authorized to.
+
+By default WorkOS comes with two environments: staging and production. The former is for development and testing, the latter for live traffic. For single-tenant applications, new environments can be added to your WorkOS account to accommodate each of your users. For more information or to request new environments, please reach out to [support](mailto:support@workos.com).
+
+## Simple B2C model
+
+![Simple B2C model](https://images.workoscdn.com/images/55ffa6da-ec2b-4f03-881c-3f68e5a2a818.png?auto=format&fit=clip&q=80)[border=false]
+
+In a simple B2C model, all users belong to the application, users do not require assignment or management by an organization in order to perform actions or access resources. In this model your customer is also the end-user, they sign up or sign in to your app in order to use your services without being associated with an organization.
+
+### User data in B2C models
+
+It's common to have a single users table in your database linking to the WorkOS user (among other services), you may optionally decide to use WorkOS as the source of truth for other user information such as `firstName`, `lastName` or `email`, though this depends on your application requirements.
+
+In this model, WorkOS's primary role is to authenticate users and store them in a simple, flat structure. This is the default model and is the simplest to implement, but as your needs grow you may find yourself needing to add additional functionality.
+
+## B2B modeling
+
+In contrast to the B2C example, a typical B2B model introduces the concept of Organizations.
+
+Organizations relate a set of users and provide a structure to manage and enforce authentication methods and resource access. We can extend our previous diagram to introduce this concept.
+
+![B2B model](https://images.workoscdn.com/images/21e07368-ab1a-460e-8dcb-499d763cbdd4.png?auto=format&fit=clip&q=80)[border=false]
+
+In this model, we have a one-to-many relationship between users and organizations, a user can belong to many organizations and an organization can have many users, this relationship is expressed by our Organization Membership table. Unlike the B2C example, the customer here is a (usually enterprise) company that has its own users, typically employees or contractors.
+
+While you can still use all the authentication methods outlined above with B2C models, the main difference between B2C and B2B is that the latter tends to prefer SSO as its authentication method of choice.
+
+This model starts to become incredibly powerful as we can now capture more complex scenarios. For example, we could leverage features such as domain verification and domain policies to control authentication behavior and provision members automatically.
+
+### Domain verification and domain policies
+
+[Domain verification](/user-management/domain-verification) is the process of proving ownership of a specific domain, typically handled by a company’s IT department. Once a domain is verified, all existing and future users with email addresses matching the domain are, by default, managed by the organization's [domain policy](/user-management/organization-policies/domain-policy). This allows the organization to control authentication and membership behavior for these users, such as requiring these users to authenticate via SSO.
+
+Users signing in with SSO with a verified email domain are automatically considered verified and do not need to complete the email verification process.
+
+### Integrating SSO with the Admin Portal
+
+When onboarding a new enterprise customer, they will likely ask to integrate their SSO connection provided by their own Identity Provider (IdP) with your application.
+
+The Admin Portal provided by WorkOS makes this process easy to implement by providing a hosted UI that guides your user through SSO configuration.
+
+![Admin Portal flow](https://images.workoscdn.com/images/77050e33-5dcc-480f-a0a7-3f46a6b33abf.png?auto=format&fit=clip&q=80)[border=false]
+
+With the Admin Portal, the process of configuring your customer’s SSO integration is reduced to creating an Organization in WorkOS, saving relevant data in your own database and then redirecting the user to the Admin Portal to guide them through the configuration flow.
+
+### User data in B2B models
+
+As with B2C models, user data on the WorkOS side can be used as the source of truth, but the far more common scenario is to store user information in your own database which links to the WorkOS user.
+
+The WorkOS User Management and SSO products can be used independently, with the latter acting as authentication middleware which intentionally does not handle user database management for your application. If you’re unsure which is best for your business, it’s recommended to stick with User Management as it gives you the aforementioned flexibility to add and/or remove features as your needs grow.
+
+## Example scenarios
+
+As your application grows you may find yourself needing to add additional features to support customer needs. WorkOS User Management is designed with this is mind. As you move upmarket and take on larger and larger customers, you can easily adopt and extend your feature set within an established architecture. The following scenarios explain some common use cases with specific feature sets.
+
+- [SSO with contractors](/user-management/sso-with-contractors) – Enforcing Organization SSO with external guest members.
+- [Invite-only Signup](/user-management/invite-only-signup) – An invite only application that allows existing users to invite new members.

package/.docs/organized/docs/user-management/organization-policies.mdx

@@ -0,0 +1,33 @@
+---
+title: Organization Authentication Policies
+description: Customize available authentication methods for each organization.
+showNextPage: true
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/user-management/organization-policies.mdx
+---
+
+## Introduction
+
+Some organizations may prefer to limit their users to specific authentication methods to meet security requirements. These organization-level customizations can be configured on the organization page in the Dashboard.
+
+## Domain policy
+
+A domain policy allows an organization to control authentication and membership behavior of users whose email domain matches one of the organization’s [verified domains](/user-management/domain-verification). Domain policies are enforced for _all_ users with email domains included in the policy, regardless of their membership status within the organization or the organization selected during sign-in.
+
+Additionally, users provisioned through a [directory](/user-management/directory-provisioning) with an email domain included in the organization's domain policy will be automatically added as active members of the organization without needing an invitation.
+
+![Configuring a domain policy in the dashboard](https://images.workoscdn.com/images/b98493d9-f9fe-475d-a448-f9099558cd19.png?auto=format&fit=clip&q=50)
+
+> Only one organization can include a specific domain in its domain policy per environment.
+
+### Requiring SSO by default
+
+When an SSO connection is first set up for an organization, all non-SSO authentication methods for the organization are automatically disabled. Typically, the IT admin who configures SSO intends for it to be the sole authentication method. Any additional methods can be enabled manually if the organization prefers.
+
+## Organization policy
+
+Unlike the domain policy, which is enforced regardless of the organization selected during sign-in, the organization policy is enforced when a member selects the specific organization during sign-in.
+
+The organization policy can require authentication via its SSO connection or require MFA. This is particularly useful for guest members who do not have an organization email domain, or when the organization cannot include an email domain in its domain policy because the domain is managed by another organization.
+
+![Configuring an organization policy in the dashboard](https://images.workoscdn.com/images/bcc25d91-602d-420f-a465-6ea790d27005.png?auto=format&fit=clip&q=50)

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

@@ -0,0 +1,46 @@
+---
+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/overview.mdx
+---
+
+## Introduction
+
+WorkOS User Management is a set of user authentication and organization security features that securely power your application. Features are designed to be flexible, while offering a fast integration to handle all of the user management complexity that comes with advanced business and customer needs.
+
+## Authentication
+
+User Management supports many authentication methods out of the box. They are designed to grow with your app, from the simplest use case all the way to complex Enterprise [SSO](/user-management/sso) for your largest customers, these include:
+
+- [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)
+
+These features are available via [AuthKit](/user-management), or through the public [API](/reference/user-management). AuthKit provides an easy to integrate, pre-built authentication flow, while integrating against the API allows you to implement your own UI and Sign In flow.
+
+## Fast integration
+
+The fastest way to integrate WorkOS User Management features is with [AuthKit](/user-management).
+
+![AuthKit Sign In UI](https://images.workoscdn.com/images/b8286e7e-3ad9-4d43-99d5-e022e6bb36fb.png?auto=format&fit=clip&q=80)
+
+AuthKit abstracts away many of the UX and WorkOS API calling concerns automatically, allowing you to focus on building your application. See the [Quick Start](/user-management) guide for more information on how to get started.
+
+## Security
+
+Adopting User Management in your app provides a wealth of security benefits.
+
+- Best-in-class [email verification](/user-management/email-verification), enabled by default.
+- Safe [identity linking](/user-management/identity-linking) and merging of duplicate accounts. This protects against spoofing and reduces the user support burden.
+- Identity Provider (IdP) differences are normalized, so that you get consistency across user profiles. This reduces the likelihood of security issues related to differing semantics across providers.
+- Automatic bot detection and blocking, to protect against brute force attacks.
+- [Multi-Factor Authentication (MFA)](/user-management/mfa) available per environment to further enhance your app’s security posture.
+
+## Getting started
+
+Start integrating User Management into your app today, check out the [Quick Start](/user-management) guide to get started with AuthKit or review the [API Reference](/reference/user-management) material.

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

@@ -0,0 +1,42 @@
+---
+title: Passkeys
+description: Configuring passkey authentication and enrollment.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/passkeys.mdx
+---
+
+## Introduction
+
+Passkey authentication allows users to sign up and sign in to your application using public-key cryptography, which is more secure than a traditional password.
+
+Passkeys are built on top of the [WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) standard that enable the user's device to securely store the passkey's private key, with access protected by biometrics, such as a fingerprint. When the user signs in, the private key is used to sign a payload that is verified with the matching public key.
+
+You can read more about how WebAuthn and passkeys work at the [official FIDO alliance passkey website](https://passkeys.dev/), the consortium behind passkey web standards.
+
+## Passkey configuration
+
+Passkeys can be enabled in the _Authentication_ section of the [WorkOS Dashboard](https://dashboard.workos.com).
+
+![The WorkOS Dashboard displaying the configuration dialog for passkeys](https://images.workoscdn.com/images/5ed77bef-cfa0-4a40-958f-d19b23a1ec1b.png)
+
+> **Developers should configure an [AuthKit custom domain](/custom-domains/authkit) before enabling passkeys in production**. Passkeys are bound to the domain they were registered on. Adding the domain later would prevent the usage of passkeys that were registered on the old domain.
+
+### Enabling progressive enrollment
+
+Optionally, your users who are still using password-based authentication can be prompted to create a passkey on their next sign-in. This flow, known as "progressive enrollment", is disabled by default but can be enabled alongside passkey authentication in the WorkOS Dashboard.
+
+![AuthKit displaying the passkey progressive enrollment prompt.](https://images.workoscdn.com/images/c541f4f6-5956-489d-be7e-c8b242c9923d.png)
+
+If users skip passkey enrollment they will be reminded every two weeks, and additionally have the option to never be prompted again if they prefer passwords.
+
+### Multi-factor auth
+
+If [MFA](/user-management/mfa) is also enabled and required, users who sign in with a passkey will not be prompted for a separate TOTP code. AuthKit treats passkeys as both a first and second factor by requiring user verification when a passkey is presented.
+
+User verification in the context of a passkey means the passkey must be combined with another "authorization gesture", like the scanning of a fingerprint, or entering a separate PIN.
+
+---
+
+## Integrating via the API
+
+Passkey authentication is currently only available in AuthKit. If you'd like to discuss an API-based integration, please reach out to [support](mailto:support@workos.com).

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

@@ -0,0 +1,127 @@
+---
+title: Radar
+description: 'Protecting against bots, fraud and abuse.'
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/user-management/radar.mdx
+---
+
+## Introduction
+
+Radar adds automated protections on top of AuthKit by collecting signals on the behavior of users as they sign in to your app.
+These signals feed into an engine that identifies abusive or anomalous behavior.
+When Radar detects a suspicious authentication attempt, it can block or challenge that attempt based on the settings you configure.
+
+Radar leverages device fingerprinting to identify which client is being used to authenticate with AuthKit.
+This enables Radar to differentiate between legitimate and malicious users, so that automated protections won't impact your app's availability during an attack.
+It's also a signal for suspicious behavior, such as when a device is used for multiple accounts or multiple devices are using the same account.
+
+## Getting Started
+
+Radar is not enabled for all AuthKit instances by default.
+If you would like to access this feature, please reach out to [our team](mailto:support@workos.com), or for current customers, drop a note in your shared Slack channel.
+
+## Dashboard
+
+Radar's dashboard provides a summary of authentication activity in your app.
+The top chart shows counts of suspicious events that Radar is detecting, along with automated actions that Radar took based on configuration.
+The counts are updated in real time to make it easy to spot spikes in anomalous behavior.
+To see historical trends, the time range for the chart can be toggled between 24 hours, 7 days and 30 days.
+
+![Radar dashboard](https://images.workoscdn.com/images/87812b47-e72f-4edb-8164-e171545c9d8d.png?auto=format&fit=clip&q=50)
+
+Below the top chart is a set of cards that show Radar detection activity for different user identifiers.
+This is helpful to understand which types of devices, locations, users, etc. have been detected most often by Radar.
+Each card is linked to the events page to drill into a list of individual event activity.
+
+![Radar identifier cards](https://images.workoscdn.com/images/a2239641-2ef4-4742-bf9c-97189069ddaa.png?auto=format&fit=clip&q=50)
+
+## Event list
+
+A complete list of Radar events appears under the "Events" tab.
+This list can be filtered by detection type, action taken, or a specific user ID or email.
+By clicking into a single event, you can view all of the metadata related to that action including device, location, user agent and IP address.
+Reviewing events in Radar can help inform when custom restrictions may be useful, such as allowing a known legitimate user to bypass detections, or blocking an IP range that is abusing your sign-in.
+
+![Radar events](https://images.workoscdn.com/images/bde4e906-d680-4f18-baa5-d33fac803a7d.png?auto=format&fit=clip&q=50)
+
+## Configuration
+
+Radar gives you full control over the automated actions that are taken to suppress suspicious activity.
+By enabling a detection, you can choose to block or challenge an authentication attempt that exhibits the detection's behavior.
+
+**Blocking** an attempt will cause the authentication to fail, even if valid credentials are provided.
+The user will see a message indicating their sign-in was not successful, and can reach out to an administrator for more detail.
+
+**Challenging** an attempt will send the user an email with a one-time passcode (OTP).
+The user is then prompted to enter that code to continue authentication.
+Challenging suspicious authentication attempts with an OTP is effective in stopping bots that are capable of solving CAPTCHAs,
+as well as malicious users who have stolen credentials but don't have access to the user's email account.
+
+**Notifying** on an attempt will send an informational email to users and/or admins when Radar detects a suspicious behavior.
+This is helpful to proactively make individuals aware that an attack might be taking place, or their account was compromised.
+
+![Radar configuration](https://images.workoscdn.com/images/f9f112c8-e731-4b8a-9e83-7bcea4527ac9.png?auto=format&fit=clip&q=50)
+
+Out of the box, Radar ships with the following detections:
+
+### Bot detection
+
+Block or challenge sign-in attempts that are initiated by a bot or program.
+
+In addition to detecting that the client is a bot, Radar can differentiate between different types of bots
+such as AI agents or search engine crawlers, giving developers the ability to control which kinds of bots are restricted.
+
+![Radar bot configuration](https://images.workoscdn.com/images/9191ad0f-e898-4044-8947-cfb388ea7952.png?auto=format&fit=clip&q=50)
+
+### Brute force
+
+Block or challenge sign-in attempts that are part of an attempt to break into accounts using brute force.
+
+These are attacks where a bad actor is trying many sign-ins over a short period of time.
+Radar leverages the device fingerprint to identify and isolate bad actors from legitimate traffic, ensuring that your users
+can use your app even when it’s under attack.
+
+![Radar brute force configuration](https://images.workoscdn.com/images/28988276-a698-4517-8d9b-48e75d4e1b2b.png?auto=format&fit=clip&q=50)
+
+### Impossible travel
+
+Block or challenge sign-in attempts that occur from different geolocations in short succession.
+
+By tracking device geolocation, Radar can detect when subsequent authentication requests are spread around the globe.
+Radar will detect if these attempts happen over a short period where it's not possible for the person to physically travel that distance
+
+![Radar impossible travel configuration](https://images.workoscdn.com/images/458b59af-a3e8-4646-b8a2-1bc04ae27e8e.png?auto=format&fit=clip&q=50)
+
+### Stale accounts
+
+Get notified when an account that has been dormant without use becomes active
+
+In contexts such as financial services, a dormant account becoming active might be an indication that the account
+has been taken over from the user and is being used for fraud.
+For these kinds of apps, Radar can notify the user and administrator if an account that hasn’t been used in a while has a sign-in attempt.
+Accounts are considered stale if there have been no successful sign-in in the past 60 days.
+
+![Radar stale account configuration](https://images.workoscdn.com/images/f7a1a8e9-61ba-4c54-9cdb-d54ae7890092.png?auto=format&fit=clip&q=50)
+
+### Unrecognized device
+
+Get notified when a device that has never been used before signs in to an account
+
+Using the device fingerprint, Radar checks if the device being used has been part of a successful sign-in before.
+If it hasn’t, both the user and an administrator can be notified by email.
+
+![Radar unrecognized device configuration](https://images.workoscdn.com/images/f574e3d9-feed-43bc-aadb-2790cbfd2ce0.png?auto=format&fit=clip&q=50)
+
+### Custom restrictions
+
+Specific user identifiers can be configured to always allow or deny an authentication attempt.
+Examples of using a custom restrictions:
+
+- Restricting sign-ins to a corporate IP range
+- Allow a script with a specific user agent to bypass bot detection
+- Banning specific devices (i.e. iPods) from using your app
+- Allowing certain users to bypass detections that are false positives
+
+> Note: the allow list takes preference -- if an user matches an identifier that is in the allow list, they will bypass all other Radar rules.
+
+![Radar restrictions configuration](https://images.workoscdn.com/images/bda02327-1d15-4e9c-b559-08b101930880.png?auto=format&fit=clip&q=50)

package/.docs/organized/docs/user-management/roles-and-permissions.mdx

@@ -0,0 +1,155 @@
+---
+title: Roles and Permissions
+description: Manage and assign roles and permissions to users.
+showNextPage: true
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/user-management/roles-and-permissions.mdx
+---
+
+## Introduction
+
+A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by unique, immutable slugs and are assigned to users through [organization memberships](/user-management/users-organizations/organizations).
+
+Permissions grant users privileged access to resources and actions in your application and are referenced in your code by unique, immutable slugs. A permission can be assigned to any number of roles.
+
+### Standalone roles
+
+Roles alone can be sufficient when your application only requires very coarse-grained access control. This is suitable if users only need to be separated into broad categories and there is minimal overlap between roles. Simple roles can be easier to manage, but are less flexible for complex access control scenarios.
+
+### Utilizing permissions with roles
+
+Permissions allow for more detailed and flexible management of access. They are particularly useful when:
+
+- You anticipate the need to frequently modify access rights or introduce new roles.
+- There is significant overlap in access rights between different roles, but with some variations.
+- You want to minimize code changes when modifying access rights. By abstracting access control checks to permissions, you can add or modify roles and their access rights without changing the application code.
+
+## Configure roles and permissions
+
+Roles and permissions are managed in their own section of the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+![Roles section WorkOS Dashboard](https://images.workoscdn.com/images/946f05f6-e25c-45ae-96f0-fb6734c18411.png?auto=format&fit=clip&q=50)
+
+### Create permissions
+
+When configuring permissions, we recommend:
+
+- Defining a common naming scheme to use across all permissions for your application. Consider separating the resource and action with a delimiter, such as `users:view`. The following delimiters are permitted: `-.:_*`.
+- Keep permission slugs clear and concise. When assigned to roles, these slugs will included as part of session cookies in the [session JWT claims](/user-management/sessions/integrating-sessions/access-token), which is limited to a maximum size of 4KB in many modern web browsers.
+
+### Assign permissions to roles
+
+Permissions can be assigned when creating a new role or when editing an existing role.
+
+![Assign permissions to a role](https://images.workoscdn.com/images/0ee8e707-0dd3-43ca-8504-8bf86fd2fb4e.png?auto=format&fit=clip&q=50)
+
+### Default role
+
+Role configuration occurs at the environment level. Each environment is seeded with a default `member` role, which is automatically assigned to every organization member. This default role cannot be deleted, but any role can be set as the default.
+
+If you need to set default roles or other role configurations at the organization level, refer to the [Organization roles](/user-management/roles-and-permissions/organization-roles) section.
+
+### Assign roles
+
+Organization memberships require a role. Every user with an organization membership is automatically assigned the default role when added to an organization. This role can be edited.
+
+<DirectorySyncDiagram.Roles />
+
+You can retrieve the role slug from the user's [organization membership object](/reference/user-management/organization-membership) to determine their access level and capabilities within your application.
+
+### Delete roles
+
+When roles are deleted, all organization memberships are reassigned to the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all organization memberships.
+
+> To migrate from one default role to another, set the new default role and delete the old one. All users will then be reassigned to the new default role.
+
+### Priority order
+
+If a user is provisioned from multiple sources with conflicting roles, the role with the highest priority will be assigned.
+
+### Role Assignment in Admin Portal
+
+Organization admins can assign roles to identity provider groups in the [Admin Portal](/admin-portal) during SSO or directory setup.
+
+From the _Roles and Permissions_ section in the WorkOS Dashboard, role assignment is an environment-level setting. However, it can also be configured per organization via the _Roles_ tab on that organization's page. If enabled, all Admin Portal sessions for the relevant SSO connection or directory will support group role assignment.
+
+![Enable directory group role assignment dashboard setting](https://images.workoscdn.com/images/157af155-1cd5-4714-9a4e-f56dd0005e36.png?auto=format&fit=clip&q=50)
+
+Whether to enable role assignment for SSO or directory groups depends on your application’s setup. When [provisioning users with Directory Sync](/user-management/directory-provisioning), we recommend enabling directory group role assignment due to [limitations of SSO role assignment](/sso/identity-provider-role-assignment/considerations/drawbacks).
+
+If you’re not yet using directory provisioning, you can enable SSO group role assignment as the environment default.
+
+Because this setting is configurable per organization, choose a sensible default based on your customers' typical setup:
+
+- **A. All organizations use SSO:**  
+  If no organizations are using Directory Sync, enable SSO group role assignment in Admin Portal at the environment level.
+
+- **B. Some organizations use Directory Sync:**  
+  Enable directory group role assignment in Admin Portal for those specific organizations.
+
+- **C. Most organizations use Directory Sync:**  
+  Enable directory group role assignment in Admin Portal at the environment level, and override the setting for organizations that only use SSO.
+
+When switching from one role assignment source to another, refer to the [section below](/user-management/roles-and-permissions/role-assignment/migrating-role-assignment-source).
+
+## Role-aware sessions
+
+When a user signs into your app, a [user session](/user-management/sessions) is initiated. The authentication response includes an access token, a JSON Web Token (JWT), with the `role` claim indicating the user organization membership's role for that session.
+
+## Role assignment
+
+You can map identity provider groups to roles to automatically assign roles to users. AuthKit supports two methods for role assignment:
+
+### SCIM
+
+Roles can be assigned via SCIM through [directory group role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment). Admins can map group memberships to roles in the Admin Portal during SCIM or Google Workspace directory setup. These mappings are used to assign roles to organization memberships via [Directory Provisioning](/user-management/directory-provisioning).
+
+### SSO
+
+Roles can also be assigned via [SSO group role assignment](/sso/identity-provider-role-assignment/sso-group-role-assignment). Groups returned in the SSO profile can be mapped to roles in the WorkOS Dashboard. If an AuthKit user authenticates via SSO and belongs to a mapped group, the corresponding role will be set on the [organization membership](/reference/user-management/organization-membership) and reflected in the [user’s session](/user-management/sessions/integrating-sessions/access-token).
+
+> Ensure [SSO JIT provisioning](/user-management/jit-provisioning/sso-jit-provisioning) is enabled for each organization using SSO role assignment.
+
+### Migrating role assignment source
+
+It’s recommended to use only one role assignment source per organization. If your organization currently uses SSO group role assignment and you'd like to switch to [directory group role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment), consider the following paths:
+
+- **A. Directory is not yet configured:**  
+  [Enable directory group role assignment](/user-management/roles-and-permissions/configure-roles-and-permissions/role-assignment-in-admin-portal) for this organization via the **Roles** tab under an organization in the WorkOS Dashboard. The organization admin will be prompted to set up directory group role assignments in the Admin Portal.
+
+- **B. Directory is already configured:**  
+  Manually assign roles to directory groups in the WorkOS Dashboard, or regenerate an Admin Portal link so the organization admin can set the role mappings there.
+
+Directory group role assignments take precedence and will override any SSO group role assignments on the organization membership. Once directory group roles are properly set up and reflected, you can delete the SSO group mappings.
+
+## Organization roles
+
+Organization roles are custom roles scoped to a particular organization. They are managed via the "Roles" tab under an organization in the WorkOS Dashboard.
+
+![Roles tab for organization](https://images.workoscdn.com/images/5c09cd78-041f-4bb9-9e76-f7267106b22c.png?auto=format&fit=clip&q=50)
+
+### Why might I use organization roles?
+
+In some cases, an application's fixed set of roles may not meet the needs of certain organizations. For example, an organization may require a lesser privileged set of permissions for their members. Organization roles allow you to create custom roles, with the organization's desired set of permissions, without affecting access control for other organizations.
+
+### Creating organization roles
+
+By default, organizations have no custom organization roles and simply inherit the environment-level roles. You can create an organization role by clicking the "Create role" button on the organization's "Roles" tab. All organization role slugs are automatically prefixed with `org`.
+
+![Create an organization role](https://images.workoscdn.com/images/90f3f3c0-3c66-48b2-b962-04b34f30599e.png?auto=format&fit=clip&q=50)
+
+### Organization role configuration
+
+Once you create the first role for an organization, that organization will have its own [default role](/user-management/roles-and-permissions/configure-roles-and-permissions/default-role) and [priority order](/user-management/roles-and-permissions/configure-roles-and-permissions/priority-order), independent from the environment.
+
+New roles added to the environment will be available to the organization and placed at the bottom of the organization's role priority order.
+
+### Using organization roles
+
+Like environment-level roles, organization roles can be used in [role assignment](/user-management/roles-and-permissions/role-assignment), [sessions](/user-management/roles-and-permissions/role-aware-sessions), and the [organization membership API](/reference/user-management/organization-membership). No additional action is required to enable this behavior after creating organization roles.
+
+### Deleting an environment role
+
+When attempting to delete an environment role that's the default role for one or more organizations, you'll be prompted to select a new default role for all affected organizations. Organization members previously assigned the deleted role will be assigned the new organization default role.
+
+![Select a replacement role](https://images.workoscdn.com/images/5e6f3e51-5de5-4bb1-a850-52b2196282b9.png?auto=format&fit=clip&q=50)