@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/pipes/index.mdx

@@ -0,0 +1,75 @@
+---
+title: Pipes
+description: >-
+  Enable your customers to connect their third-party accounts to your
+  application.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/pipes.mdx
+---
+
+## Introduction
+
+Pipes allows your users to securely connect their third-party accounts to your
+application. With Pipes, you can easily integrate with popular services like
+GitHub, Slack, Google, Salesforce, and many more without managing OAuth flows,
+token refresh logic, or credential storage.
+
+## Configuring providers
+
+To make an provider available to your users, you will need to configure it in
+the WorkOS Dashboard.
+
+Visit the _Pipes_ section of the WorkOS Dashboard to get started. Click _Connect
+provider_ then choose the provider from the list. If you don’t see the provider
+you need, please reach out to [our team](mailto:support@workos.com).
+
+![A screenshot of a GitHub provider being configured via the Pipes page in the WorkOS Dashboard](https://images.workoscdn.com/images/88a1f135-53ba-4d26-92ef-6c61e924e178.png?auto=format&fit=clip&q=50)
+
+### Shared Credentials
+
+For the fastest setup, you can use WorkOS-managed shared credentials in sandbox
+environments. This allows users to connect immediately without requiring you to
+create OAuth applications with each provider.
+
+1. Specify the required **scopes** for your application.
+2. Provide an optional **description**. This will be used in the widget to inform users
+   on how your application will use their data from the provider.
+
+### Custom Credentials
+
+For production applications, configure the provider with your own OAuth credentials:
+
+1. **Create an OAuth application** within the provider's dashboard.
+   1. You can find instructions on setting up the provider in the documentation section of the setup modal.
+1. Use the provided **redirect URI** when configuring the provider.
+1. Set the **client ID and secret** from the provider.
+1. Specify the required **scopes** for your application.
+   1. You may need to set these scopes in the provider configuration as well.
+1. Provide an optional **description**. This will be used in the widget to inform users
+   on how your application will use their data from the provider.
+
+Commonly used scopes are provided in-line, but you should consult each provider's documentation for the full list of available scopes.
+
+## Provider management in your application
+
+The [Pipes Widget](/widgets/pipes) provides a pre-built UI for users to connect
+and manage their connected accounts. The widget shows the user which
+providers are available, and lets them easily initiate the authorization
+flow. It communicates with the WorkOS API and stores the connection information
+for the user. If there's ever a problem with the user’s access token, the widget
+will let them know they need to reauthorize.
+
+![Pipes widget screenshot](https://images.workoscdn.com/images/e84a33bb-0510-4d85-9041-33b1a0ce938c.png?auto=format&fit=clip&q=50)
+
+> The description in the widget is set in the provider's configuration in the WorkOS Dashboard.
+
+## Fetching access tokens
+
+Once a user has connected a provider, you can [fetch access tokens](/reference/pipes) from your
+backend to make API calls to the connected service on their behalf. Pipes takes
+care of refreshing the token if needed, so you’ll always have a fresh token. If
+there’s a problem with the token, the endpoint will return information about the issue so you can
+direct the user to the correct it. This may require sending the user to re-authorize directly
+or via the page with the Pipes widget.
+
+<CodeBlock file="pipes-fetch-token" />

package/.docs/organized/docs/pipes/providers.mdx

@@ -0,0 +1,9 @@
+---
+title: Providers
+description: Explore the third-party providers available for Pipes integrations.
+originalPath: .tmp-workos-clone/packages/docs/content/pipes/providers.mdx
+---
+
+Configure providers and find setup instructions in the [dashboard](https://dashboard.workos.com/environment/pipes).
+
+<PipesProvidersTable />

package/.docs/organized/docs/rbac/_navigation.mdx

@@ -0,0 +1,16 @@
+---
+title: RBAC
+links:
+  - title: Overview
+    url: /rbac
+  - title: Configuration
+    url: /rbac/configuration
+  - title: Integration
+    url: /rbac/integration
+  - title: Organization Roles
+    url: /rbac/organization-roles
+  - title: IdP Role Assignment
+    url: /rbac/idp-role-assignment
+originalPath: .tmp-workos-clone/packages/docs/content/rbac/_navigation.mdx
+---
+

package/.docs/organized/docs/rbac/configuration.mdx

@@ -0,0 +1,80 @@
+---
+title: Configuration
+description: Configure roles and permissions
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/rbac/configuration.mdx
+---
+
+## Overview
+
+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 via [organization memberships](/authkit/users-organizations/organizations). Role assignments can be sourced manually or from Identity Provider (IdP) group mappings (SSO or Directory Sync).
+
+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.
+
+> Role and permission configuration applies to [all integrations](/rbac/integration).
+
+---
+
+## Configure 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.
+
+![Roles section WorkOS Dashboard](https://images.workoscdn.com/images/09c8fb23-5748-4236-914e-79849ac03a9a.png?auto=format&fit=clip&q=50)
+
+You can manage roles in the _Authorization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/environment/authorization/) or using the [Roles API](/reference/roles).
+
+Role slugs are immutable and cannot be changed after creation. Environment role slugs are unique within an environment. [Organization role](/rbac/organization-roles) slugs are unique within an organization.
+
+### 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](/authkit/roles-and-permissions/organization-roles) section.
+
+### Multiple roles
+
+All [integrations](/rbac/integration) support multiple roles across directory users, SSO profiles, and organization memberships. For any user, if role(s) are not explicit set, they will receive the default role.
+
+Multiple roles is disabled by default. To manage this setting, open the [Authorization](https://dashboard.workos.com/environment/authorization/configuration) configuration page and scroll to the _Multiple Roles_ section.
+
+> Multiple roles is an **environment-level** setting and applies to all organizations in that environment.
+
+### Priority order
+
+Role priority order is used for [IdP role assignment](/rbac/idp-role-assignment) to resolve conflicts when a user belongs to multiple mapped groups. The highest-priority role wins. Priority order also determines which role will be assigned to users when migrating from a multiple roles to single role configuration in the environment.
+
+### Delete roles
+
+When roles are deleted:
+
+- **Single-role (default):** All affected organization memberships, SSO profiles, and directory users are reassigned to the **default role**.
+- **Multiple-roles:** The deleted role is **removed** from each organization membership that has it, any other roles on the membership remain intact.
+
+Deletion is asynchronous, so updates may take a moment to propagate.
+
+> **Tip:** To migrate from one default role to another, set the new default, then delete the old one—users will be reassigned automatically.
+
+---
+
+## Configure permissions
+
+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.
+
+### Create permissions
+
+You can manage permissions in the _Authorization_ section of the [WorkOS Dashboard](https://dashboard.workos.com/environment/authorization/permissions) or using the [Permissions API](/reference/roles/permission).
+
+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](/authkit/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/f6fd6d9a-a7b0-4df7-908b-b657e669a3dc.png?auto=format&fit=clip&q=50)

package/.docs/organized/docs/rbac/idp-role-assignment.mdx

@@ -0,0 +1,79 @@
+---
+title: IdP Role Assignment
+description: Map identity provider groups to roles to automatically assign roles to users
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/rbac/idp-role-assignment.mdx
+---
+
+## Overview
+
+Identity Provider (IdP) role assignment is the process of mapping identity provider groups to roles to automatically assign roles to users.
+
+Users are assigned to groups via the identity provider. Groups usually correspond to roles in your app. Therefore, IT admins will often map a group one-to-one to a role. This can be defined within the WorkOS dashboard or Admin Portal for your application to receive automatic role updates.
+
+## Role assignment sources
+
+### Directory Sync
+
+Roles can be assigned from the identity provider via Directory Sync through [directory group role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment). Admins can map groups to roles in the Admin Portal during SCIM and Google Workspace directory setup.
+You can also manage these assignments in the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+Enterprise organizations typically use SSO to manage user authentication and SCIM (Directory Sync) for user lifecycle management.
+While access management can be automated through either SSO or SCIM, SCIM is generally the preferred option due to its real-time synchronization capabilities.
+
+### SSO
+
+Roles can be assigned from the identity provider via SSO through [SSO group role assignment](/sso/identity-provider-role-assignment/sso-group-role-assignment). Admins can map groups to roles in the Admin Portal during SSO connection setup.
+You can also manage these assignments in the [WorkOS Dashboard](https://dashboard.workos.com/). SSO group role assignment is supported in both SAML and OIDC-based connection types, except for Google OIDC due to [a limitation](https://issuetracker.google.com/issues/133774835?pli=1) with the groups claim.
+
+A key limitation of SSO-based role assignment is that changes made in the identity provider (IdP) only take effect after the user re-authenticates. In contrast, SCIM propagates changes immediately without requiring user interaction, enabling applications to revoke sessions and enforce access updates in real time.
+
+> If your organization has a directory connection configured, it is recommended to use the [directory for role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment).
+
+## AuthKit integration
+
+If you are [integrating with AuthKit](/authkit/roles-and-permissions/role-assignment), our full user management solution, roles are automatically assigned to the appropriate [organization membership](/reference/authkit/organization-membership). These roles are also reflected in the [user’s session token](/authkit/sessions/integrating-sessions/access-token), ensuring consistent access control across your application.
+
+When using SSO group role assignment, roles are populated on the organization membership through SSO groups, allowing role assignment based on your customer’s identity provider configuration each time a user authenticates.
+
+When using Directory Sync group role assignment, roles are populated on the organization membership through [directory provisioning](/authkit/directory-provisioning), allowing for seamless, real-time role assignment based on your customer’s identity provider configuration.
+
+## Priority order
+
+If a user is provisioned from multiple groups with conflicting roles, the role with the highest priority will be assigned. If using multiple roles, priority order should be ignored.
+
+![Edit role priority dialog](https://images.workoscdn.com/images/3c6946c2-4ff1-41e4-b10f-568339dc3a2b.png?auto=format&fit=clip&q=50)
+
+## Multiple roles
+
+When [multiple roles is enabled](/rbac/configuration/configure-roles/multiple-roles), users can receive multiple roles through identity provider group memberships. This applies to both [SSO group role assignment](/sso/identity-provider-role-assignment) and [Directory Sync group role assignment](/directory-sync/identity-provider-role-assignment).
+
+### How multiple roles work with IdP assignment
+
+- **All applicable roles assigned**: Users receive all roles from groups they belong to that have explicit role mappings
+- **Union of permissions**: Users get the combined permissions from all assigned roles
+- **Priority order ignored**: When multiple roles are enabled, priority order is not used since users receive all applicable roles
+- **Minimum one role**: Every user must have at least one role - if no groups have explicit mappings, the user receives the [default role](/rbac/configuration)
+
+### Example scenario
+
+If a user is a member of both "Engineering" and "Design" groups in their identity provider:
+
+- **Single role mode**: User receives the highest priority role (e.g., "Engineering")
+- **Multiple roles mode**: User receives both "Engineering" and "Designer" roles
+
+This prevents "role explosion" where you would otherwise need to create hybrid roles like "designer-engineer" for every possible combination.
+
+## Explicit vs. default role assignments
+
+Explicit role assignments are created by manually mapping an IdP group to a role in the WorkOS Admin Portal or Dashboard.
+
+Default role assignments are created for any IdP group that does not have an explicit role mapping. Default group role assignments are always mapped to the configured [default role](/rbac/configuration/configure-roles/default-role).
+
+## Role assignment in Admin Portal
+
+You can choose to show or hide the role assignment step in Admin Portal, and whether to show the steps for Directory Sync or SSO at an environment level on the _Authorization_ page in the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+![Role assignment in Admin Portal dialog](https://images.workoscdn.com/images/fe19e3ac-6370-404e-9590-cdb06b3de127.png?auto=format&fit=clip&q=50)
+
+For your customers that may have a different setup, you can override the role assignment in Admin Portal setting per-organization, on the _Roles_ tab of the organization page in the [WorkOS Dashboard](https://dashboard.workos.com/). For example, if most customers use Directory Sync but a few only use SSO, select "Directory groups" role assignment at the environment level, and select "Single Sign-On groups" at the organization level for the exceptions.

package/.docs/organized/docs/rbac/index.mdx

@@ -0,0 +1,24 @@
+---
+title: Role-Based Access Control (RBAC)
+description: Assign roles and manage access for users and organizations
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/rbac/index.mdx
+---
+
+## Introduction
+
+WorkOS Role-Based Access Control (RBAC) is an authorization system designed for managing access to applications using a flexible roles and permissions model. With WorkOS RBAC, teams can also define custom roles at the organization or tenant level, assign permissions to those roles, and enforce access policies at scale. RBAC also supports role assignment from identity provider (IdP) groups, making it easy to integrate with Single Sign-On (SSO) and Directory Sync workflows for seamless, enterprise-ready access control.
+
+## Key features
+
+- Fully managed authorization service for defining and enforcing access controls across your application
+- Configure roles, permissions, and organization-level roles directly in the [WorkOS Dashboard](https://dashboard.workos.com) or using the [API](/reference/roles)
+- Seamless integration with [AuthKit user management](/authkit) by assigning roles via API and enforcing access through session JWTs
+- Support for enterprise features like organization-scoped roles and IdP role assignment via SSO and Directory Sync allowing your customers to automatically map roles from their identity provider to streamline enterprise onboarding
+- Fully integrated with [WorkOS Widgets](/widgets), including role management through the User Management Widget
+
+## Additional resources
+
+- [The developer's guide to RBAC](https://workos.com/guide/the-developers-guide-to-rbac)
+- [8 Role-Based Access Control (RBAC) examples in action](https://workos.com/blog/role-based-access-control-example)
+- [How to build RBAC with WorkOS and Node](https://workos.com/blog/rbac-with-workos-and-node)

package/.docs/organized/docs/rbac/integration.mdx

@@ -0,0 +1,59 @@
+---
+title: Integrating Role-Based Access Control
+description: Utilize Role-Based Access Control across WorkOS products
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/rbac/integration.mdx
+---
+
+## Configure roles and permissions
+
+Before integrating with WorkOS Role-Based Access Control (RBAC), you’ll need to [configure roles and permissions](/rbac/configuration) for your application in the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+---
+
+## Integrating with AuthKit
+
+WorkOS RBAC seamlessly integrates with AuthKit to provide a complete user management solution. Using AuthKit, you can assign roles directly to organization memberships, source roles from your customer’s identity provider (IdP), and read roles and permissions directly from session JWTs.
+
+### Assigning roles
+
+In AuthKit, users are associated with [organizations](/reference/organization) via [organization memberships](/reference/authkit/organization-membership). Each organization membership has role(s), which represents a user’s access level for that particular organization. Every organization membership is automatically assigned the [default role](/rbac/configuration/configure-roles/default-role) when added to an organization.
+
+You can modify an organization membership’s role(s) via the [organization memberships API](/reference/authkit/organization-membership/create), [WorkOS Dashboard](https://dashboard.workos.com/), or via [IdP role assignment](/rbac/assignments/idp-role-assignment).
+
+[IdP role assignment](/rbac/idp-role-assignment) will always take precedence over roles assigned via API or the WorkOS Dashboard. For [SSO group role assignment](/sso/identity-provider-role-assignment/sso-group-role-assignment), the organization membership role updates each time the user authenticates. For [directory group role assignment](/directory-sync/identity-provider-role-assignment/directory-group-role-assignment) via [directory provisioning](/authkit/directory-provisioning), the organization membership’s role updates each time we receive a directory event for the user.
+
+### Single vs. multiple roles
+
+AuthKit, Directory Sync, and Single Sign-On all support both single and [multiple role](/authkit/roles-and-permissions/multiple-roles) paradigms. There are two ways to assign multiple roles:
+
+- **Group-based assignment**: if a user is a member of multiple groups with role mappings, they will receive all the roles. This applies to directory users, SSO profiles, and organization memberships when using [directory](/authkit/directory-provisioning) or [SSO JIT provisioning](/authkit/jit-provisioning/sso-jit-provisioning) in AuthKit.
+- **Manual assignment**: multiple roles can be assigned to [organization memberships](/reference/authkit/organization-membership) directly via the WorkOS Dashboard or [API](/reference/authkit/organization-membership/create).
+
+Multiple roles helps to avoid needing to create roles for every possible combination of permissions e.g., designer-engineer. This model fits teams where users span functions or need additive, temporary access.
+
+For most apps, start with **single-role** assignments for simplicity and predictability, and adopt multiple roles only when overlapping permission sets become common.
+
+### Using roles and permissions in your app
+
+Read a user’s role(s) from their [organization membership](/reference/authkit/organization-membership) or from an [AuthKit session access token](/authkit/sessions/integrating-sessions/access-token).
+
+---
+
+## Integrating with Directory Sync
+
+For [standalone Directory Sync](/directory-sync), organization administrators manage roles through [directory group role assignment](/directory-sync/identity-provider-role-assignment). Their assigned role defines the user’s access level for the particular [organization](/reference/organization) and is based on their directory group memberships.
+
+All [directory users](/reference/directory-sync/directory-user) have assigned roles. If no role is explicitly assigned through directory group role assignment, the user receives the [default role](/rbac/configuration/configure-roles/default-role). Roles are granted to directory users in real-time, when we receive updates to their group memberships.
+
+Role slugs are returned on [Directory User](/reference/directory-sync/directory-user) objects from the API. These can be used to assign a role to your internal user object.
+
+---
+
+## Integrating with Single Sign-On (SSO)
+
+For [standalone SSO](/sso), organization administrators manage roles via [SSO group role assignment](/sso/identity-provider-role-assignment). Their assigned role defines the user’s access level for the particular [organization](/reference/organization).
+
+All [SSO profiles](/reference/sso/profile) have assigned roles. If no role is explicitly assigned through SSO group role assignment, the user receives the [default role](/rbac/configuration/configure-roles/default-role). Roles are granted to SSO profiles when the user authenticates.
+
+Role slugs are returned on [SSO Profile](/reference/sso/profile) objects from the API. These can be used to assign a role to your internal user object based on group memberships.

package/.docs/organized/docs/rbac/organization-roles.mdx

@@ -0,0 +1,38 @@
+---
+title: Organization Roles
+description: Create and manage custom organization-scoped roles
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/rbac/organization-roles.mdx
+---
+
+## Overview
+
+Organization roles are custom roles scoped to a particular organization. They are managed via the _Roles_ tab under an organization in the [WorkOS Dashboard](https://dashboard.workos.com/) or using the [Organization Roles API](/reference/roles/organization-role). You can utilize organization roles regardless of whether you're integrating with AuthKit, SSO, or Directory Sync.
+
+![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 or using the [Organization Roles API](/reference/roles/organization-role/create). 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](/authkit/roles-and-permissions/configure-roles-and-permissions/default-role) and [priority order](/authkit/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](/authkit/roles-and-permissions/role-assignment), [sessions](/authkit/roles-and-permissions/role-aware-sessions), and the [organization membership API](/reference/authkit/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)

package/.docs/organized/docs/rbac/quick-start.mdx

@@ -0,0 +1,52 @@
+---
+title: Quick Start
+description: >-
+  Set up roles & permissions to model your authorization requirements. Then use
+  the SDK to make access checks from your application.
+originalPath: .tmp-workos-clone/packages/docs/content/rbac/quick-start.mdx
+---
+
+## Before getting started
+
+To get the most out of this guide, you should have:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+- Your WorkOS [API Key](/glossary/api-key)
+
+## What you'll build
+
+In this guide, we’ll implement role-based access control for a simple B2B video sharing SaaS application, where users can view and create videos, and elevated roles can manage other users’ roles and application settings.
+
+We will:
+
+1. Map your application’s access management model to a set of roles
+2. Define permissions to control granular access to your application’s resources
+3. Associate permissions with roles, and configure default roles and priority order
+4. If using AuthKit, assign roles to organization memberships and determine access via the [session JWT](/reference/authkit/session-tokens)
+5. If using standalone SSO, access user roles through the [SSO Profile object](/reference/sso/profile)
+6. If using standalone Directory Sync, access user roles through the [Directory User object](/reference/directory-sync/directory-user)
+
+## API resource definitions
+
+[Role](/reference/roles)
+: Represents a logical grouping of access management rules.
+
+---
+
+## (1) Create roles
+
+The first step to RBAC is to determine the application's access management hierarchy.
+
+---
+
+## (2) Create permissions
+
+The first step to RBAC is to define
+
+Get provider-specific instructions by selecting the directory provider you want to test:
+
+---
+
+## Summary
+
+That's it! We've now setup a powerful RBAC system for our application.