@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/fga/high-cardinality-entities.mdx

@@ -0,0 +1,172 @@
+---
+title: High-Cardinality Entities
+description: >-
+  Learn when to use FGA for authorization and when to handle access control in
+  your application.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/high-cardinality-entities.mdx
+---
+
+## Overview
+
+We recommend using FGA for lower-cardinality resources and handling high-cardinality entities in your application. This guide explains why and shows you how.
+
+---
+
+## Why FGA works well for lower-cardinality resources
+
+Lower-cardinality resources like workspaces, projects, and environments are natural boundaries for role assignments:
+
+- **Users need explicit roles** — You assign someone as a project editor or workspace admin
+- **Sharing matters** — You grant external collaborators access to specific resources
+- **Permissions vary by resource** — Different teams have different access to different projects
+- **Long-lived and stable** — These resources are created infrequently and change slowly, so keeping them in FGA is straightforward
+
+High-cardinality entities like rows, artifacts, and messages rarely need this. You don't typically assign someone as a "row editor" or "message viewer" — they inherit access from the container they're in. Defining roles and permissions for millions of individual messages would be operationally complex without adding value.
+
+---
+
+## Why keep high-cardinality entities out of FGA
+
+Some authorization systems encourage storing entities such as individual files, messages, and rows as relationships in FGA. After working with many customers on authorization design, we've found this creates more problems than it solves. High-cardinality entities are created frequently, change often, and exist in volumes that make keeping two systems in sync impractical. Your database is already the source of truth for these entities, and access is almost always inherited from a parent container rather than granted individually.
+
+---
+
+## What to sync vs. keep local
+
+**Sync to FGA (lower cardinality):**
+
+- Organizations, workspaces, projects
+- Environments, pipelines, apps
+- Repositories, dashboards, teams
+
+**Keep in your application (high cardinality):**
+
+- Individual files, messages, comments
+- Row-level data within tables
+- Logs, events, audit records
+- Anything with millions of instances per organization
+
+---
+
+## The pattern: nearest FGA-managed parent
+
+To check access to high-cardinality entities, your application should traverse up to the nearest FGA-managed parent before making the authorization check:
+
+```typescript
+async function canUserAccessFile(
+  organizationMembershipId: string,
+  fileId: string,
+): Promise<boolean> {
+  // 1. Look up the file to find its parent project
+  const file = await db.files.findUnique({ where: { id: fileId } });
+  if (!file) return false;
+
+  // 2. Check access at the project level (FGA-managed)
+  const { authorized } = await workos.authorization.check({
+    organizationMembershipId,
+    permissionSlug: 'project:view',
+    resourceTypeSlug: 'project',
+    resourceExternalId: file.projectId,
+  });
+
+  return authorized;
+}
+```
+
+---
+
+## Nested folder example
+
+For deeply nested structures, walk up the hierarchy to find the FGA-managed parent:
+
+```typescript
+async function canUserAccessFolder(
+  organizationMembershipId: string,
+  folderId: string,
+): Promise<boolean> {
+  const MAX_DEPTH = 25;
+  const visited = new Set<string>();
+  let currentFolderId = folderId;
+
+  // Walk up the folder hierarchy
+  while (visited.size < MAX_DEPTH) {
+    if (visited.has(currentFolderId)) {
+      // Cycle detected
+      return false;
+    }
+    visited.add(currentFolderId);
+
+    const folder = await db.folders.findUnique({
+      where: { id: currentFolderId },
+    });
+    if (!folder) return false;
+
+    // Found the FGA-managed parent
+    if (folder.projectId) {
+      const { authorized } = await workos.authorization.check({
+        organizationMembershipId,
+        permissionSlug: 'project:view',
+        resourceTypeSlug: 'project',
+        resourceExternalId: folder.projectId,
+      });
+      return authorized;
+    }
+
+    // Continue up the hierarchy
+    if (!folder.parentFolderId) return false;
+    currentFolderId = folder.parentFolderId;
+  }
+
+  // Exceeded max depth
+  return false;
+}
+```
+
+---
+
+## Fast path with JWT claims
+
+For organization-level permissions, you can skip the FGA API call entirely by checking JWT claims:
+
+```typescript
+async function canUserAccessFile(
+  session: Session,
+  fileId: string,
+): Promise<boolean> {
+  // Fast path: check org-level permission from JWT
+  if (session.permissions?.includes('project:view')) {
+    return true;
+  }
+
+  // Slow path: check resource-level permission via FGA
+  const file = await db.files.findUnique({ where: { id: fileId } });
+  if (!file) return false;
+
+  const { authorized } = await workos.authorization.check({
+    organizationMembershipId: session.organizationMembershipId,
+    permissionSlug: 'project:view',
+    resourceTypeSlug: 'project',
+    resourceExternalId: file.projectId,
+  });
+
+  return authorized;
+}
+```
+
+---
+
+## Benefits of this approach
+
+- **No sync overhead** — High-cardinality entities stay in your database, not FGA
+- **Single source of truth** — Your database owns the entity data
+- **Fast path available** — JWT claims can skip API calls for org-level permissions
+- **Flexible traversal** — Your app controls how entities map to FGA resources
+
+---
+
+## Next steps
+
+- [Resources](/fga/resources) — Register and manage FGA resources
+- [Access Checks](/fga/access-checks) — Perform authorization checks
+- [AuthKit Integration](/fga/authkit-integration) — Embed permissions in access tokens

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

@@ -0,0 +1,66 @@
+---
+title: IdP Role Assignment
+description: >-
+  Map identity provider groups to organization roles while preserving
+  resource-scoped access.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/idp-role-assignment.mdx
+---
+
+## Introduction
+
+IdP role assignment lets you map identity provider groups to organization-level roles. When an IT admin adds someone to the "Engineering" group in Okta or Azure AD, they automatically get the corresponding role in your application.
+
+Today, IdP role assignment supports organization-level roles only. Resource-scoped roles are managed through the API. A user can have both—their organization role from the IdP, plus granular resource roles assigned by your application.
+
+> Support for mapping IdP groups to resource-scoped roles is coming soon.
+
+---
+
+## How it works
+
+**Organization layer (IdP-managed)** – Users get baseline access based on IdP groups. Everyone in "Engineering" might get `org-member`.
+
+**Resource layer (API-managed)** – Users get specific access to workspaces and projects via API assignments.
+
+When IdP groups change, only organization roles update. Resource-scoped assignments stay intact.
+
+```text
+Alice's roles:
+├─ org-member (from IdP group: "Engineering")
+├─ workspace-admin on Workspace: Platform (API assignment)
+└─ project-editor on Project: API Backend (API assignment)
+```
+
+---
+
+## Setting up IdP role assignment
+
+Role mappings are configured in the [WorkOS Dashboard](https://dashboard.workos.com/) or through the Admin Portal.
+
+![Role assignment in Admin Portal dialog](https://images.workoscdn.com/images/fe19e3ac-6370-404e-9590-cdb06b3de127.png?auto=format&fit=clip&q=50)
+
+For setup instructions, see [Directory Sync role assignment](/directory-sync/identity-provider-role-assignment) for real-time updates via SCIM, or [SSO role assignment](/sso/identity-provider-role-assignment) for authentication-time assignment.
+
+---
+
+## Directory Sync vs. SSO
+
+**Directory Sync (recommended)** – Role changes happen in real-time via SCIM. Access can be revoked immediately when someone leaves a group.
+
+**SSO only** – Role assignments are evaluated at authentication time. Changes take effect on the next sign-in.
+
+---
+
+## Combining with FGA
+
+Use IdP groups for baseline organization access, and API assignments for elevated resource access:
+
+```text
+From IdP:
+└─ org-member (baseline access to view workspaces and projects)
+
+From API:
+├─ workspace-admin on Workspace: Platform (team leads)
+└─ project-viewer on Project: Client Portal (contractors)
+```

package/.docs/organized/docs/fga/index.mdx

@@ -1,60 +1,125 @@
 ---
 title: Fine-Grained Authorization (FGA)
-description: 'Scalable, centralized, fine grained authorization for your application.'
+description: Scalable fine-grained authorization built for B2B SaaS.
 showNextPage: true
 originalPath: .tmp-workos-clone/packages/docs/content/fga/index.mdx
 ---
 
 ## Introduction
 
-WorkOS Fine-Grained Authorization (FGA) is a centralized authorization service for customer applications. Teams can use FGA to implement a custom authorization model tailor-made for their application(s), with the ability to integrate elements of role-based access control (RBAC), relationship-based access control (ReBAC), and attribute-based access control (ABAC) as needed.
+Fine-Grained Authorization (FGA) extends the existing WorkOS RBAC system to handle the complex, fast-changing authorization needs of modern B2B SaaS products.
 
-## Key features
+Most products start with simple, tenant-wide roles like Admin and Member. As adoption grows, the authorization model must account for new and changing app resources and requirements, like workspaces, projects, apps, pipelines, nested tenants, custom roles, group-based collaboration, and enterprise exceptions. What used to evolve over a decade can now change in 12–18 months. Teams patch RBAC with special cases, multiply role variants, and eventually face full rewrites.
 
-- Fully managed, centralized authorization service (inspired by Google Zanzibar) for managing and enforcing application authorization
-- [Check API](/reference/fga/check) to perform fast access checks from your application (i.e. `Is user:A an editor of document:X?`)
-- [Query API](/reference/fga/query) to quickly lookup which resources users have access to from your application (i.e. `Which documents can user:A edit?`)
-- Central log of all authorization events & operations to make auditing and debugging of your application(s) easy
-- Pre-built templates for common access control patterns like RBAC, multi-tenancy, pricing tiers & feature entitlements, and more
+FGA is designed as the next step in that evolution. It keeps the mental model of RBAC—roles, permissions, assignments—while adding hierarchical, resource-scoped access control. It integrates natively with WorkOS products you're already using: RBAC, SSO, Directory Sync, AuthKit, and IdP role assignment. It can be adopted incrementally, with no data migration or confusing schema DSL.
 
-## Common Use Cases
+The goal is a single authorization foundation that adapts as your product and customer requirements change, without forcing conceptual rewrites.
 
-### Role-based access control (RBAC)
+---
+
+## Core concepts
+
+FGA formalizes three building blocks:
+
+**Subjects** are the users, groups, devices, or agents that can be granted access. Today that's primarily organization memberships (users), with support for other subject types coming soon.
+
+**Resources** are the business entities in your product—organizations, workspaces, projects, apps—arranged in a hierarchy. Permissions flow down this hierarchy automatically.
+
+**Privileges** are the roles and permissions that define what subjects can do. Roles are scoped to resource types and can include permissions for child resource types, enabling powerful inheritance.
+
+The key shift from traditional tenant-wide RBAC is that resources and their hierarchy are first-class. Roles and permissions are scoped to specific resource types and can be assigned at any level of that hierarchy.
+
+---
+
+## Building blocks
+
+### Resource types
+
+[Resource types](/fga/resource-types) define the schema of your authorization model. They describe what kinds of entities exist — workspaces, projects, apps — and how they relate to one another. You configure resource types in the WorkOS Dashboard, creating the blueprint for your application's entity hierarchy.
+
+### Resources
+
+[Resources](/fga/resources) are instances of resource types created at runtime. When a user creates a workspace or project in your application, you register a corresponding resource in WorkOS with a type, an ID, and a parent.
+
+### Roles and permissions
+
+[Roles and permissions](/fga/roles-and-permissions) are scoped to specific resource types. A role describes what someone can do within the scope of a particular resource. Permissions can apply to the same resource type or inherit up to parent resource types.
+
+### Assignments
+
+[Assignments](/fga/assignments) bind an organization membership to a role on a specific resource. Support for other subject types like profiles, directory users, agents, and services is coming soon. When a role includes child-type permissions, those permissions propagate down the hierarchy automatically.
+
+### Access checks
 
-One of the most common forms of access control, role-based access control involves 3 main entities: roles, permissions and users. Permissions define _behaviors_ that are grouped together into roles (e.g. admin, owner). Roles are then assigned to users to grant them the ability to perform a group of behaviors. RBAC is common within B2B software and SaaS applications used by enterprises, often being necessary to meet regulatory, compliance, and/or enterprise contract requirements.
+[Access checks](/fga/access-checks) answer the question: "Can this user perform this action on this resource?" You can also ask "Which resources can this user access?" or "Who has access to this resource?" FGA considers all the ways a user might have access—roles assigned directly, roles inherited from parent resources, and organization-level roles.
 
-### Custom roles
+---
+
+## Hierarchical permission inheritance
+
+The defining feature of FGA is that permissions flow down the resource hierarchy automatically. A workspace admin can access all projects and apps within that workspace without needing separate assignments at each level.
+
+![Example resource hierarchy with roles](https://images.workoscdn.com/images/74c1fad7-abe9-4c21-a244-8c2563f1313c.png?auto=format&fit=clip&q=50)
+
+In this example, users have roles at different levels of the hierarchy. An organization member can view everything beneath the organization. A project editor can edit a specific project and its apps. An app editor has access only to a single app. The hierarchy does the work of propagating permissions—you assign a role once, and access flows down to all children.
 
-Most applications start by implementing RBAC with a static set of roles. This works well for simple applications used by one customer (single-tenant). However, this model often breaks down in multi-tenant applications (apps used by multiple customers). Different customers might require a different set of roles or a different mapping of roles to permissions. This requirement introduces a new dimension (tenant) on top of existing roles, permissions, and users, requiring a flexible access model to prevent a problem known as _role explosion_.
+This model reduces the number of role assignments you need to manage while giving you precise control when you need it. For a detailed walkthrough of how this works, see [Roles and Permissions](/fga/roles-and-permissions).
 
-### Fine-grained access control (FGAC)
+---
+
+## Adoption path
 
-Fine-grained access control is a more granular form of access control that is becoming popular in applications today. As opposed to the coarse-grained access control provided by RBAC, which grants access to behaviors across _all resources_, FGAC allows applications to grant users certain behaviors _per resource_.
+FGA works alongside the existing RBAC product. No migrations are required—existing roles and organization memberships continue working, and you can adopt FGA incrementally.
 
-For example, while a RBAC rule might specify that `[admins] can [edit] [reports]`, a fine grained rule can specify that `[user:1] can [edit] [report:xsd34]`.
+A typical rollout looks like:
 
-### Resource-level RBAC
+1. Keep using current RBAC for organization-level access
+2. Define resource types in the Dashboard to mirror your product structure
+3. Begin registering resource instances as entities are created
+4. Introduce resource-scoped roles like `workspace-admin` or `project-editor`
+5. Add Authorization API checks where you need resource-level control
+6. Assign resource roles via API (IdP group mapping for resources coming soon)
 
-FGAC can also be used in conjunction with RBAC to enable what we call 'fine-grained RBAC'. This is especially common in SaaS apps and developer tools. For example, let's take a cloud infrastructure multi-tenant SaaS that defines a resource called `customer-application`. A 'customer-application' can have `owners`, `editors` and `viewers`. Now let's say that the users within this SaaS can have multiple 'roles' within their 'tenant' based on their access level. In order to specify an access rule like `all [admins] of [tenant:x] can [edit] [all applications] that belong to [tenant:x]`, we need 'fine-grained RBAC', or the ability to specify resource-level rules by role.
+You don't need to convert everything at once. Start with one feature, prove the model works, then expand.
 
-### Collaboration & document sharing
+---
 
-One of the most common use cases for FGAC is to enable access control on user-generated content, similar to Google Docs or Box. With FGAC, you can easily define `owners`, `editors` and `viewers` of your own resources and objects (ex. documents, reports).
+## AuthKit integration
 
-### Organization hierarchies
+FGA integrates with [AuthKit](/fga/authkit-integration) to provide role-aware sessions. Organization-level roles and their permissions are embedded directly in access tokens, enabling instant checks for org-wide features without API calls. For resource-scoped permissions, the Authorization API evaluates against the full hierarchy.
 
-Another common use case for FGAC is to model complex organization hierarchies, often those found within most mid-large scale enterprises. For example, let's say that we'd like to specify a rule within an organization which states that `all [members] of [team:x] can access [report:y87dXfd]`. Furthermore, let's say that membership in `team:x` is driven by org hierarchy and whether a specific person reports to a given manager.
+This two-layer approach—JWT for org-wide, API for resources—gives you fast checks where possible and precise control where needed.
+
+---
 
-Using a FGA system, we can model the exact org hierarchy as well as easily define rules such as `all [direct reports] of [manager:y] are [members] of [team:x]` and `all [members] of [team:x] can access [report:y87dXfd]` in order to process queries such as `can [user:1] access [report:y87dXfd]` in realtime.
+## Enterprise identity mapping
+
+For enterprise customers, [IdP role assignment](/fga/idp-role-assignment) allows organizations to map identity provider groups to organization-level roles. When someone joins the "Engineering" group in Okta or Azure AD, they automatically get the corresponding role.
+
+Resource-scoped role assignments remain managed via API, giving you a clean separation: IT admins control baseline organization access through their identity provider, while your application manages who has access to which specific resources.
+
+---
+
+## Performance and scalability
+
+FGA is designed for real-time authorization:
+
+- **Sub-50ms p95** access checks
+- **Strong consistency**—role changes take effect immediately
+- **High availability** for production workloads
+- **Warmed caches** to minimize cold starts
+- **Edge caches** for low-latency global access (coming soon)
+
+---
 
-### Regional access control
+## Coming soon
 
-Similar to enterprise org hierarchies, apps with complex regional hierarchies are a good use case for FGAC. For example, let's say we're building a supply-chain or operations-focused SaaS app where data and functionality is separated by region. We may have `region:east` and `region:west` to distinguish the two core regions with teams and users defined within each region.
+We're continuing to expand FGA with new capabilities:
 
-Using a FGA system, we can accurately model the regions and easily make queries against it at runtime to ensure that the right users have access to the right data and functionality.
+**User groups and teams** – Assign a group of users to a resource or group of resources. Instead of individual assignments, grant access to an entire team at once.
 
-### Pricing tiers & feature entitlements
+**IdP role assignment for sub-resources** – Map identity provider groups directly to resource-scoped roles, not just organization-level roles. Your customers' IT admins will be able to control workspace and project access through their IdP.
 
-Although not directly related to security, a common form of access control often used within SaaS is what we call 'pricing tiers & feature entitlements'. Pricing tiers are groups of features within an app, typically assigned based on the end customer's payment tier. Mature SaaS apps often build out their own management and enforcement layer for pricing tiers, in order to support everything from feature overrides and metering to integrations with payment systems.
+**Permission assignment** – Assign or exclude specific permissions for a user, enabling patterns like "grant access to all resources except this one" without creating custom roles.
 
-With a FGAC system, pricing tiers and feature entitlements can be expressed as rules like `[company:x] is on [tier:enterprise]` and `[feature:dashboard] is part of [tier:enterprise]` in order to easily support runtime queries like `can [user:y] which is a member of [company:x] access [feature:dashboard]?`
+**Further performance enhancements** – Continued optimization of access check endpoints for even lower latency at scale.