@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/feature-flags/index.mdx

@@ -0,0 +1,80 @@
+---
+title: Feature Flags
+description: >-
+  Manage rollout of new features for specific users and organizations with
+  Feature Flags.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/feature-flags/index.mdx
+---
+
+## Overview
+
+Feature flags are a tool that allows teams to control the rollout of features in real time. They enable businesses to separate feature delivery from code deployment, creating a more agile and risk-managed approach to launching and managing product experiences.
+
+WorkOS Feature Flags provides a developer-friendly solution that integrates seamlessly with your existing authentication flow. Create and manage flags through the dashboard then access them through a user's access token. Feature flags can target organizations or individual users. This approach lets you safely roll out new functionality, enable beta programs for select customers, and manage premium feature access without deploying code changes.
+
+## Use cases
+
+- **Targeted rollouts:** Enable features for specific organizations before a general release
+- **Beta programs:** Allow early access to new features for select customers
+- **Premium features:** Restrict advanced functionality to organizations on higher-tier plans
+
+## Before getting started
+
+To get the most out of these guides, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+
+- An existing organization in your WorkOS Dashboard
+
+![WorkOS Dashboard UI showing organization creation](https://images.workoscdn.com/images/1c69fd98-01be-491d-9255-58363bc6a983.png?auto=format&fit=clip&q=50)
+
+## API object definitions
+
+[Organization](/reference/organization)
+: Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.
+
+[User](/reference/authkit/user)
+: Describes a user who can be targeted with feature flags.
+
+## (1) Create a feature flag from the WorkOS dashboard
+
+- Sign in to your [WorkOS dashboard](https://dashboard.workos.com/) account and navigate to the Feature Flags page.
+- Click the `Create feature flag` button and enter a name, slug, and description.
+
+![A screenshot showing the WorkOS dashboard feature flags page.](https://images.workoscdn.com/images/9be5d8f6-8956-47fc-aca6-66478bb37881.png?auto=format&fit=clip&q=80)
+
+Feature flags are created across all environments, allowing you to test your feature flag in a sandbox environment before enabling it in production.
+
+---
+
+## (2) Set the users and organizations that should have access
+
+To edit which set of users and organizations should have the feature flag enabled, click `Edit` on the rule for the environment you want to edit. Next, select your desired rule setting between `None`, `Some`, and `All`. Selecting `Some` will allow you select specific users and organizations.
+
+To edit a feature flag's rules in other environments, click the `Edit in X` button which will update your active dashboard environment to the selected environment, allowing you to update rules in the chosen environment.
+
+![A screenshot showing the configuration of a feature flag organization rule.](https://images.workoscdn.com/images/bf958da9-1288-464c-b087-b54f60f03171.png?auto=format&fit=clip&q=80)
+
+![A screenshot showing the configuration of a feature flag user rule.](https://images.workoscdn.com/images/32f8b6da-d357-4ac7-b9b3-96c9cf3ef60f.png?auto=format&fit=clip&q=80)
+
+---
+
+## (3) Enable the feature flag
+
+Once you're ready to enable the feature for the configured set of organizations and users, toggle the flag on to start including it in a user's access token when they authenticate for a configured organization or when the user is individually targeted.
+
+![A screenshot showing the enabling of a feature flag.](https://images.workoscdn.com/images/f526ab53-0ec5-4261-abe5-24f05e92cdd8.png?auto=format&fit=clip&q=80)
+
+---
+
+## (4) Use the feature flags in your application
+
+The access token includes the `feature_flags` claim, containing the user’s entitlements. You can use this information to gate access to features in your application.
+
+Feature flags will show up in the access token the next time the user logs in or the session is refreshed. You can manually [refresh the session](/reference/authkit/authentication/refresh-token) after granting the organization access in the dashboard.
+
+<CodeBlock>
+  <CodeBlockTab title="Server-side" file="feature-flags-example" />
+  <CodeBlockTab title="Client-side" file="feature-flags-example-client" />
+</CodeBlock>

package/.docs/organized/docs/feature-flags/slack-notifications.mdx

@@ -0,0 +1,58 @@
+---
+title: Slack Notifications
+description: Get notifications about feature flag changes in your Slack workspace.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/feature-flags/slack-notifications.mdx
+---
+
+## Introduction
+
+Feature flags give teams precise control over feature releases. The WorkOS app for Slack sends real-time notifications throughout your feature flags' lifecycle, from creation and enabling to deletion. This keeps all stakeholders informed about critical changes, such as when a feature flag is enabled for specific customers or organizations.
+
+---
+
+## Configure your Slack connection
+
+To set up Slack notifications, navigate to [_Feature Flags_](https://dashboard.workos.com/environment/flags) and click _Enable Slack notifications_.
+
+![A screenshot showing the WorkOS Dashboard Feature Flags page](https://images.workoscdn.com/images/840a7450-12bf-4d8d-ba12-b30da70912d7.png?auto=format&fit=clip&q=50)
+
+Next, click _Connect to Slack_ to go to the Slack Installation page.
+
+![A screenshot showing the WorkOS Dashboard Slack notifications dialog when no connection exists](https://images.workoscdn.com/images/7b873377-4847-43ae-a7ba-bf50b25d9f5e.png?auto=format&fit=clip&q=50)
+
+Finally, select the channel that you'd like to get your notifications in. By default, notifications are sent for all production environments in your WorkOS account.
+
+![A screenshot showing the Slack installation page](https://images.workoscdn.com/images/83ed7c7f-1e27-4b52-b20e-6439cec854a9.png?auto=format&fit=clip&q=50)
+
+---
+
+## Slack notifications
+
+Once your Slack notifications are enabled, you'll start to receive messages in the configured channel for all feature flag events.
+
+### Flag lifecycle events
+
+- A flag is created
+- A flag's details are updated (name, description, tags)
+- A flag is deleted
+
+![Sample message of a flag created event](https://images.workoscdn.com/images/1bc973f6-f879-4c71-8f0a-fd3eece4f252.png?auto=format&fit=clip&q=50)
+
+### Rule updates and targeting changes
+
+- A flag is enabled or disabled
+- Targeting is changed between All, Some, or None
+- Specific users or organizations are added or removed
+
+![Sample message of a flag enabled for some event](https://images.workoscdn.com/images/9613033e-f313-449d-bbd3-9bcff85af2c2.png?auto=format&fit=clip&q=50)
+
+---
+
+## Disconnect an existing connection
+
+To disable notifications or to change your configured Slack channel, you must disconnect the existing connection. To start, navigate to [_Feature Flags_](https://dashboard.workos.com/environment/flags) and click _Connected to Slack_.
+
+![A screenshot showing the WorkOS Dashboard Slack notifications dialog for an existing connection](https://images.workoscdn.com/images/1c2e2fad-af7a-48a4-8b93-75b93653ed2b.png?auto=format&fit=clip&q=50)
+
+Next, click _Disconnect_ and confirm to disable Slack notifications to the listed channel.

package/.docs/organized/docs/fga/_navigation.mdx

@@ -1,64 +1,44 @@
 ---
-title: Fine-Grained Authorization
+title: FGA
 links:
-  - title: Getting Started
+  - title: Overview
+    url: /fga
+  - title: Quick Start
+    url: /fga/quick-start
+  - title: Core Concepts
     links:
-      - title: Overview
-        url: /fga
-      - title: Quick Start
-        url: /fga/quick-start
-      - title: Playground
-        url: /fga/playground
-  - title: Key Concepts
-    links:
-      - title: Schema
-        url: /fga/schema
-      - title: Warrants
-        url: /fga/warrants
+      - title: Resource Types
+        url: /fga/resource-types
       - title: Resources
         url: /fga/resources
-      - title: Policies
-        url: /fga/policies
-      - title: Query Language
-        url: /fga/query-language
-      - title: Warrant Tokens
-        url: /fga/warrant-tokens
-      - title: Operations & Usage
-        url: /fga/operations-usage
-  - title: Management
+      - title: Roles and Permissions
+        url: /fga/roles-and-permissions
+      - title: Assignments
+        url: /fga/assignments
+      - title: High-Cardinality Entities
+        url: /fga/high-cardinality-entities
+  - title: Access Control
+    links:
+      - title: Access Checks
+        url: /fga/access-checks
+      - title: Resource Discovery
+        url: /fga/resource-discovery
+  - title: Integrations
     links:
-      - title: Schema Management
-        url: /fga/schema-management
-      - title: Local Development
-        url: /fga/local-development
-      - title: Identity Provider Sessions
-        url: /fga/identity-provider-sessions
-  - title: Modeling
+      - title: AuthKit Integration
+        url: /fga/authkit-integration
+      - title: Standalone Integration
+        url: /fga/standalone-integration
+      - title: IdP Role Assignment
+        url: /fga/idp-role-assignment
+  - title: Migration Guides
     links:
-      - title: Org Roles & Permissions
-        url: /fga/modeling/org-roles-and-permissions
-      - title: Custom Roles
-        url: /fga/modeling/custom-roles
-      - title: Google Docs
-        url: /fga/modeling/shareable-content
-      - title: Entitlements
-        url: /fga/modeling/entitlements
-      - title: User Groups
-        url: /fga/modeling/user-groups
-      - title: Managed Service Provider
-        url: /fga/modeling/managed-service-provider
-      - title: Attribute-Based Access Control
-        url: /fga/modeling/abac
-      - title: Conditional Roles
-        url: /fga/modeling/conditional-roles
-      - title: Policy Context
-        url: /fga/modeling/policy-context
-      - title: Public Access
-        url: /fga/modeling/public-access
-      - title: Superusers
-        url: /fga/modeling/superusers
-      - title: Blocklists
-        url: /fga/modeling/blocklist
+      - title: Migrate from OpenFGA
+        url: /fga/migration-openfga
+      - title: Migrate from SpiceDB
+        url: /fga/migration-spicedb
+      - title: Migrate from Oso Cloud
+        url: /fga/migration-oso
 originalPath: .tmp-workos-clone/packages/docs/content/fga/_navigation.mdx
 ---
 

package/.docs/organized/docs/fga/access-checks.mdx

@@ -0,0 +1,109 @@
+---
+title: Access Checks
+description: Ask whether a user can perform an action on a resource.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/access-checks.mdx
+---
+
+## Overview
+
+Access checks answer: "Can this user do this action on this resource?"
+
+FGA looks at all the ways the user might have access—a role assigned directly on the resource, a role on a parent resource that grants inherited permissions, or an organization-level role. If any grant the permission, the user is authorized.
+
+---
+
+## A quick example
+
+Alice wants to deploy an app. Here's her access:
+
+```text
+Org: Acme (Alice: org-member)
+└─ Workspace: Engineering (Alice: workspace_admin)
+   └─ Project: Web
+      └─ App: Frontend
+```
+
+**Can Alice deploy App: Frontend?** Yes—her `workspace-admin` role includes `app:deploy`, which flows down to all apps in that workspace.
+
+---
+
+## Checking permissions
+
+**JWT (fast)** – For org-wide permissions, check the token directly. No API call needed. Good for navigation and feature flags.
+
+**API (precise)** – For resource-specific permissions, call the authorization API:
+
+```bash
+curl https://api.workos.com/authorization/organization_memberships/om_01HXYZ/check \
+  -X POST \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "permission_slug": "project:edit",
+    "resource_id": "authz_resource_01HXYZ"
+  }'
+```
+
+Response:
+
+```json
+{
+  "authorized": true
+}
+```
+
+For best performance, check the JWT first for org-wide permissions, then fall back to the API for resource-specific checks.
+
+---
+
+## Integrating access checks in your application
+
+Here's how you might protect an API endpoint that updates a project. Before performing the operation, check whether the user has the `proj:edit` permission on the specific project they're trying to modify:
+
+```javascript
+import { WorkOS } from '@workos-inc/node';
+
+const workos = new WorkOS(process.env.WORKOS_API_KEY);
+
+app.patch('/projects/:projectId', async (req, res) => {
+  const { organizationMembershipId } = req.user;
+  const { projectId } = req.params;
+
+  // Check if the user can edit this project
+  const { authorized } = await workos.authorization.check({
+    organizationMembershipId,
+    permissionSlug: 'proj:edit',
+    resourceExternalId: projectId,
+    resourceTypeSlug: 'project',
+  });
+
+  if (!authorized) {
+    return res.status(403).json({ error: 'Forbidden' });
+  }
+
+  // User is authorized — proceed with the update
+  const project = await updateProject(projectId, req.body);
+  return res.json(project);
+});
+```
+
+The `check()` method evaluates all possible sources of access — direct assignments on the project, inherited permissions from a parent workspace, and organization-level roles. You don't need to check each level yourself.
+
+---
+
+## Common use cases
+
+**Protecting actions** – Before a user performs an action, check if they're allowed. Return 403 if not.
+
+**Showing or hiding UI** – Check permissions before rendering to show edit buttons, delete options, or admin settings only to authorized users.
+
+**Filtering lists** – Only show resources the user can access in navigation and search results.
+
+---
+
+## Performance
+
+- **Sub-50ms** response times (p95)
+- **Strong consistency**—role changes take effect immediately
+- **High availability** for production workloads

package/.docs/organized/docs/fga/assignments.mdx

@@ -0,0 +1,124 @@
+---
+title: Role Assignments
+description: Grant users access to specific resources through role assignments.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/assignments.mdx
+---
+
+## Introduction
+
+Assignments are where authorization becomes concrete. An assignment connects a user (through their organization membership) to a role on a specific resource. This determines what actions the user can take on that resource and, through inheritance, its children.
+
+---
+
+## Creating assignments
+
+Assign a role to a user on a resource:
+
+```bash
+curl https://api.workos.com/authorization/organization_memberships/om_01HXYZ/role_assignments \
+  -X POST \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "role_slug": "workspace-admin",
+    "resource_id": "authz_resource_01HXYZ"
+  }'
+```
+
+The assignment takes effect immediately—the next access check will include it.
+
+## How assignments work
+
+When you assign a role to a user on a resource:
+
+1. The user gains all permissions included in that role on that resource
+2. If the role includes child-type permissions, those propagate down to child resources
+3. The assignment takes effect immediately
+
+For example, a `workspace-admin` role might include `workspace:edit`, `proj:read`, `proj:edit`, `app:read`, and `app:edit`. If you assign Alice this role on Workspace: Engineering, she can edit the workspace, view and edit all projects within it, and read and edit all apps in those projects. One assignment, broad access.
+
+---
+
+## Direct vs. inherited access
+
+Users can gain access through two paths: direct assignment on a resource, or inheritance from a parent.
+
+**Direct assignment** means the role is assigned specifically on that resource. Alice has `project-editor` on Project: API Backend—she can edit that project because you explicitly granted it.
+
+**Inherited access** comes from a role on a parent resource that includes child-type permissions. Alice has `workspace-admin` on Workspace: Engineering, which includes `project:edit`. That means she can edit Project: API Backend (which is in the Engineering workspace) even without a direct assignment on the project.
+
+When deciding where to assign roles, consider the scope of access needed. If someone needs access to everything in a workspace, assign a workspace role. If they need access to just one project, assign a project role directly. Both approaches are valid—the right choice depends on what access you're trying to grant.
+
+---
+
+## Multiple roles
+
+Users can always have multiple resource-scoped roles — there's no setting to control this. A user can be a `workspace-admin` on one workspace and a `project-viewer` on a project in a different workspace simultaneously.
+
+For organization-level roles, multiple roles must be [explicitly enabled](/authkit/roles-and-permissions/multiple-roles). When enabled, the permissions from all organization-level roles combine additively.
+
+A user might have `project-editor` and `project-reviewer` on the same project, giving them permissions from both roles. Or they might have `workspace-admin` on one workspace and `project-viewer` on a project in a different workspace—each assignment grants access to its respective resource tree.
+
+```text
+Alice's assignments:
+├─ org-member on Organization: Acme
+├─ workspace-admin on Workspace: Engineering
+└─ project-viewer on Project: Sensitive (in different workspace)
+```
+
+In this example, Alice has baseline org access, full control of the Engineering workspace and everything in it, plus read-only access to a sensitive project in another part of the organization.
+
+---
+
+## Managing assignments
+
+List assignments for a user:
+
+```bash
+curl "https://api.workos.com/authorization/organization_memberships/om_01HXYZ/role_assignments" \
+  -H "Authorization: Bearer sk_example_123456789"
+```
+
+Remove an assignment:
+
+```bash
+curl https://api.workos.com/authorization/organization_memberships/om_01HXYZ/role_assignments/role_assignment_01HXYZ \
+  -X DELETE \
+  -H "Authorization: Bearer sk_example_123456789"
+```
+
+Access is revoked immediately. Removing an assignment also removes any permissions that were inherited by child resources through that assignment. However, any direct assignments on child resources remain intact.
+
+You can view assignments in the [WorkOS Dashboard](https://dashboard.workos.com/). Navigate to an organization membership to see all role assignments for that user.
+
+![FGA assignments](https://images.workoscdn.com/images/c9a27787-a97c-4e8b-ac86-05cba25374ae.png?auto=format&fit=clip&q=50)
+
+---
+
+## Cascading events
+
+Several operations affect assignments automatically:
+
+**When a resource is deleted**, all role assignments on that resource and its children are removed. Users lose access without any manual cleanup.
+
+**When an organization membership is removed**, all of that user's role assignments within the organization are removed. They can no longer access any resources in that organization.
+
+**When a role's permissions change**, everyone with that role immediately sees the updated permissions. You don't need to re-assign roles—existing assignments use the new permission set.
+
+---
+
+## Combining with IdP role assignment
+
+For enterprise customers using identity providers, you can use [IdP role assignment](/fga/idp-role-assignment) for organization-level roles while managing resource-scoped roles through the API.
+
+```text
+From IdP:
+└─ org-member (baseline organization access)
+
+From API:
+├─ workspace-admin on Workspace: Engineering
+└─ project-editor on Project: Mobile
+```
+
+This gives IT admins control over who belongs to the organization and what baseline access they get, while your application manages the specifics of who can do what on which resources.

package/.docs/organized/docs/fga/authkit-integration.mdx

@@ -0,0 +1,92 @@
+---
+title: AuthKit Integration
+description: Use FGA with AuthKit for role-aware sessions and seamless authorization.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/authkit-integration.mdx
+---
+
+## Introduction
+
+FGA integrates with [AuthKit](/authkit) to provide two layers of authorization. Organization-level roles and permissions are embedded directly in the session token for instant checks. Resource-scoped permissions are checked through the [Authorization API](/fga/access-checks).
+
+---
+
+## What's in the session token
+
+When a user authenticates, their session token includes organization-level role information:
+
+```json
+{
+  sub: "user_01HXYZ..."
+  org_id: "org_01HXYZ..."
+  role: "org_member"
+  permissions: ["org:view", "workspace:view", "project:view"]
+}
+```
+
+Your application can check these permissions directly from the token without making API calls.
+
+### Why only organization-level roles?
+
+Resource-scoped roles are intentionally excluded from the JWT:
+
+- **Token size** – Users might have roles on hundreds of resources, bloating the JWT beyond practical limits
+- **Freshness** – Resource assignments change frequently; stale tokens would cause mismatches
+- **Performance** – Larger tokens mean slower requests and verification
+
+For resource-level permissions, use the [Authorization API](/fga/access-checks)—it's fast and always current.
+
+---
+
+## FGA and organization memberships
+
+FGA role assignments are scoped to organization memberships, not users directly. When you assign a role on a resource, the subject is the organization membership ID (`om_...`), which represents a user's relationship to a specific organization.
+
+This means FGA access checks require the organization membership ID rather than the user ID. You can include this ID in your JWT using [JWT Templates](/authkit/jwt-templates):
+
+```json
+{
+  "organization_membership_id": "{{ organization_membership.id }}"
+}
+```
+
+This produces a token with the membership ID alongside the default claims:
+
+```json
+{
+  "sub": "user_01HXYZ...",
+  "org_id": "org_01HXYZ...",
+  "role": "org_member",
+  "permissions": ["org:view", "workspace:view"],
+  ...
+  "organization_membership_id": "om_01HXYZ..."
+}
+```
+
+Your application can then extract the membership ID from the JWT and pass it to FGA access checks without needing an additional API call.
+
+---
+
+## Two layers of authorization
+
+**Organization layer (JWT)** – Check the token directly for org-wide features like navigation and settings. Instant, no API call needed.
+
+**Resource layer (API)** – Call the Authorization API for specific resource access. Checks the full permission hierarchy including inheritance.
+
+```text
+Can this user edit this project?
+
+1. Quick check: Does the JWT include project:edit for all projects?
+   → If yes, authorized (no API call)
+
+2. Otherwise: Call the API for this specific project
+   → Checks direct assignments and inheritance
+```
+
+---
+
+## When roles change
+
+**API checks** reflect changes immediately.
+
+**JWT permissions** require a session refresh since the token was issued at sign-in. Resource roles aren't in the JWT, so API checks always return current data.