@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/fga/modeling/conditional-roles.mdx

@@ -0,0 +1,99 @@
+---
+title: Conditional Roles
+description: >-
+  Combine relationship-based access control (ReBAC) with attribute-based access
+  control (ABAC) to create conditional roles.
+originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/conditional-roles.mdx
+---
+
+> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=conditional_roles), where you can interact with the schema, warrants, and access checks in real-time!
+
+Use FGA to combine **Relationship-Based Access Control (ReBAC)** and **Attribute-Based Access Control (ABAC)**. Define roles that are bound to specific resources and change based on specific conditions. This allows for more granular control over who can do what, when, and under which circumstances.
+
+## When to Use It
+
+Use conditional roles when you cannot determine access by relationships alone. For example, a team member may be allowed to approve some expenses, but only if they are below a certain amount or belong to specific cost centers. As systems grow in complexity, pure ReBAC or ABAC models may become limiting. Conditional roles help bridge that gap with clear, composable rules.
+
+## Example Applications
+
+- **Expense Management**: Finance managers can approve expense reports only if the amount is below a defined threshold and aligned with their assigned cost centers.
+- **Procurement**: Department heads may approve purchase orders only after completing mandatory compliance or budget authorization training.
+- **Healthcare Systems**: Authorized clinicians can access sensitive health records only if the individual is assigned to their care team and the access occurs during regulated working hours.
+
+## Schema
+
+```fga
+version 0.3
+
+type user
+
+type team
+  relation finance_admin [user]
+  relation finance_manager [user]
+
+  inherit finance_manager if
+      relation finance_admin
+
+type expense
+  relation approval_team [team]
+  relation submitter [user]
+
+  relation approve []
+  inherit approve if
+    any_of
+      all_of
+        relation finance_manager on approval_team [team]
+        policy can_approve_amount
+      all_of
+        relation finance_admin on approval_team [team]
+        policy is_high_value_expense
+
+policy can_approve_amount(expense_attributes map, user_attributes map) {
+  let can_approve_cost_center = expense_attributes.cost_center in user_attributes.approved_cost_centers;
+  let can_approve_amount = expense_attributes.amount <= 1000;
+
+  can_approve_cost_center && can_approve_amount
+}
+
+policy is_high_value_expense(expense_attributes map) {
+  expense_attributes.amount > 1000
+}
+```
+
+## Example
+
+### (1) Apply the schema
+
+Create a file called `schema.txt` containing the schema definition from above. Then use the CLI to apply this schema to your WorkOS FGA environment.
+
+> Note: make sure to select the correct environment with the [CLI](https://github.com/workos/workos-cli?tab=readme-ov-file#usage)
+
+```shell
+workos fga schema apply schema.txt
+```
+
+---
+
+### (2) Create warrants
+
+Create warrants that associate users, teams, and expenses. The example schema defines the following relationships:
+
+- users with teams (using the `finance_admin` or `finance_manager` roles)
+- teams with expenses (using the `approval_team` relation)
+
+Let's create a few warrants between team `finance-1`, expense `expense-1`, and user `user_2oDscjroNWtzxzYEnEzT9P7VYEe`:
+
+<CodeBlock title="Create warrants" file="conditional-roles-create-warrants" />
+
+---
+
+### (3) Check access
+
+With our environment setup, we can check the user's permission to approve expenses.
+
+<CodeBlock
+  title="Check if a user can approve an expense"
+  file="conditional-roles-check"
+/>
+
+---

package/.docs/organized/docs/fga/modeling/custom-roles.mdx

@@ -0,0 +1,90 @@
+---
+title: Custom Roles
+description: >-
+  Allow B2B customers to create org-scoped custom roles and map them to a static
+  set of permissions that grant capabilities in your application.
+originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/custom-roles.mdx
+---
+
+> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=custom_roles), where you can interact with the schema, warrants, and access checks in real-time!
+
+Customizable, role-based access control gives customers the freedom to define their own custom roles and map each one to a subset of the permissions offered by your application.
+
+## When to Use it
+
+Implement custom roles when:
+
+- **Role-based access control**: Your application's requirements call for role-based access control (RBAC).
+- **Custom roles**: Your customers need the ability to define custom roles that are scoped to their organization and map them to a static set of permissions in your application.
+
+## Schema
+
+```fga title="schema.txt"
+version 0.3
+
+type user
+
+type role
+  relation member [user]
+
+type organization
+  relation can_read_company_info [role]
+  relation can_write_company_info [role]
+  relation can_read_reports [role]
+  relation can_write_reports [role]
+
+  inherit can_read_company_info if
+    any_of
+      relation can_write_company_info
+      relation member on can_read_company_info [role]
+
+  inherit can_write_company_info if
+    relation member on can_write_company_info [role]
+
+  inherit can_read_reports if
+    any_of
+      relation can_write_reports
+      relation member on can_read_reports [role]
+
+  inherit can_write_reports if
+    relation member on can_write_reports [role]
+
+```
+
+## Example
+
+### (1) Apply the schema
+
+Create a file called `schema.txt` containing the schema definition from above. Then use the CLI to apply this schema to your WorkOS FGA environment.
+
+> Note: make sure to select the correct environment with the [CLI](https://github.com/workos/workos-cli?tab=readme-ov-file#usage)
+
+```shell
+workos fga schema apply schema.txt
+```
+
+---
+
+### (2) Create warrants
+
+Create warrants that associate organizations, roles, and users. The example schema defines the following relationships:
+
+- users with organizations
+- users with custom roles (e.g. `org:acme:read-only`)
+
+Let's create a few warrants between organization `acme`, role `org:acme:read-only`, and user `user_2oDscjroNWtzxzYEnEzT9P7VYEe`:
+
+<CodeBlock title="Create warrants" file="custom-roles-create-warrants" />
+
+---
+
+### (3) Check access
+
+With our environment setup, we can check the user's permission to read company info.
+
+<CodeBlock
+  title="Check if a user has a permission in their organization"
+  file="custom-roles-check"
+/>
+
+---

package/.docs/organized/docs/fga/modeling/entitlements.mdx

@@ -0,0 +1,127 @@
+---
+title: Feature Entitlements
+description: >-
+  Restrict access to features in your SaaS application based on subscription
+  tier using FGA policies and relation-based access control.
+originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/entitlements.mdx
+---
+
+> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=entitlements), where you can interact with the schema, warrants, and access checks in real-time!
+
+In SaaS applications, it's common to control access to product features based on a subscription tier. This approach allows product teams to define distinct experiences for different customer segments—like offering basic tools to free users/organizations and premium features to paying ones.
+
+For example, a design tool might offer a `Free` tier with limited capabilities and a `Pro` tier that unlocks collaboration and team-based workflows.
+
+## When to Use It?
+
+Use feature entitlements when:
+
+- Your product has multiple pricing tiers with different access levels.
+- You want to gate advanced features behind specific subscription plans.
+- Fine-grained resource access is controlled by subscription level.
+
+Use this approach when you need dynamic, policy-driven access control for features across different plans or user types. It’s especially helpful in multi-tenant SaaS apps where access logic needs to scale cleanly and stay centralized.
+
+## Example Applications
+
+- **B2B SaaS Platforms**: Unlock additional collaboration tools for premium customers.
+- **Design Tools**: Offer project and team management to higher-tier subscribers.
+- **Analytics Services**: Gate advanced reporting or integrations behind Enterprise plans.
+- **Productivity Software**: Provide shared team workspaces for Pro users.
+
+## Schema
+
+```fga
+version 0.3
+
+type user
+
+type organization
+  relation admin [user]
+  relation member [user]
+
+  inherit member if
+    relation admin
+
+  // Tiers are defined by subscription attributes
+  relation pro_subscriber []
+  inherit pro_subscriber if
+    all_of
+      relation admin // In this example, you must be an admin on the org to get access to pro features
+      policy is_pro_subscriber
+
+  relation free_subscriber []
+  inherit free_subscriber if
+    any_of
+      policy is_free_subscriber
+      policy is_pro_subscriber // Pro subscribers can also access free features
+
+  // Feature access based on subscription tier
+  relation feature_projects []
+  inherit feature_projects if
+    all_of
+      relation member
+      relation free_subscriber
+
+  relation feature_teams []
+  inherit feature_teams if
+    relation pro_subscriber
+
+// Teams and Projects demonstrate how you can utilize ReBAC permissions
+//  to control access to features based on org subscription tiers
+type team
+  relation owner [organization]
+
+  relation view []
+  inherit view if
+    relation feature_teams on owner [organization]
+
+type project
+  relation owner [organization]
+
+  relation view []
+  inherit view if
+    relation feature_projects on owner [organization]
+
+// Policies check subscription attributes passed from a third party integration
+policy is_pro_subscriber(subscription_attrs map) {
+  subscription_attrs.subscription_tier == "pro"
+}
+
+policy is_free_subscriber(subscription_attrs map) {
+  subscription_attrs.subscription_tier == "free"
+}
+```
+
+> Note: Feature access is determined entirely by an organization’s subscription attributes, which are evaluated by policy. This approach enables dynamic, attribute-based access control without manually managing feature grants.
+
+---
+
+## Example
+
+### (1) Apply the schema
+
+Create a file called `schema.txt` with the schema above, and apply it to your FGA environment using the CLI.
+
+```shell
+workos fga schema apply schema.txt
+```
+
+---
+
+### (2) Add warrants
+
+Create warrants that associate users to organizations and add teams / projects.
+
+<CodeBlock title="Create warrants" file="entitlements-create-warrants" />
+
+### (3) Check access
+
+Once everything is set up, check if a user can access specific features.
+
+<CodeBlock
+  title="Check if a user can access a feature"
+  file="entitlements-check"
+/>
+
+---

package/.docs/organized/docs/fga/modeling/managed-service-provider.mdx

@@ -0,0 +1,131 @@
+---
+title: Managed Service Provider
+description: >-
+  Model a managed service provider (MSP) that provides services to clients and
+  manages projects, tasks, and assets.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/fga/modeling/managed-service-provider.mdx
+---
+
+> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=managed_service_provider), where you can interact with the schema, warrants, and access checks in real-time!
+
+In a managed service provider (MSP) scenario, a client organization grants access to an external provider to perform services or manage resources on its behalf, while retaining control over access by assigning roles to the provider and its personnel.
+
+## When to Use It?
+
+This model is ideal when you need to grant limited access to external service providers without compromising internal access controls. It’s particularly useful in scenarios where external teams (like IT consultants, marketing agencies, or law firms) are brought in to manage specific projects or assets.
+
+- **IT services**: Clients delegate infrastructure or helpdesk support to an MSP.
+- **Marketing agencies**: Agencies manage campaigns and related assets for clients.
+- **Law firms**: External legal teams manage cases and documents for clients.
+- **Project management**: Providers handle maintenance tasks and asset management for clients.
+- **Warehousing**: Providers manage inventory and logistics for clients.
+
+## Schema
+
+```fga title="schema.txt"
+version 0.3
+
+type user
+
+// A client is a customer of the provider
+type client
+    relation admin [user]
+
+// A provider is a service provider managed by the client
+type provider
+    relation admin [user]
+    relation technician [user]
+
+    inherit technician if
+        relation admin
+
+// A project is a project managed by the client and assigned a provider
+type project
+    relation client [client]
+    relation provider [provider]
+    relation editor [user]
+    relation viewer [user]
+
+    inherit editor if
+        any_of
+            relation admin on client [client]
+            relation admin on provider [provider]
+            relation technician on provider [provider]
+
+    inherit viewer if
+        any_of
+            relation editor
+
+type task
+    relation assignee [user]
+    relation project [project]
+    relation edit []
+    relation view []
+
+    inherit edit if
+        any_of
+            relation assignee
+            relation editor on project [project]
+
+    inherit view if
+        any_of
+            relation edit
+            relation viewer on project [project]
+
+type asset
+    relation manager [user]
+    relation project [project]
+    relation edit []
+    relation view []
+
+    inherit edit if
+        any_of
+            relation manager
+            relation editor on project [project]
+
+    inherit view if
+        any_of
+            relation edit
+            relation viewer on project [project]
+
+```
+
+## Example
+
+### (1) Apply the schema
+
+Create a file called `schema.txt` containing the schema definition from above. Then use the CLI to apply this schema to your WorkOS FGA environment.
+
+> Note: make sure to select the correct environment with the [CLI](https://github.com/workos/workos-cli?tab=readme-ov-file#usage)
+
+```shell
+workos fga schema apply schema.txt
+```
+
+---
+
+### (2) Create warrants
+
+Create warrants that associate users, clients, providers, and projects. The example schema defines the following relationships:
+
+- clients and providers with projects
+- tasks and assets as children of projects
+- users with clients or providers (using one of the defined roles: `admin` or `technician`)
+
+Let's create a few warrants between client `client-1`, provider `provider-1`, project `project-1`, and users:
+
+<CodeBlock title="Create warrants" file="msp-create-warrants" />
+
+---
+
+### (3) Check access
+
+With our environment setup, we can check whether the user can view an asset.
+
+<CodeBlock
+  title="Check if a user has permission to view an asset"
+  file="msp-check"
+/>
+
+---

package/.docs/organized/docs/fga/modeling/org-roles-and-permissions.mdx

@@ -0,0 +1,95 @@
+---
+title: Org Roles & Permissions
+description: >-
+  Create org-scoped roles based on common user personas and map them to a static
+  set of permissions that grant capabilities in your application.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/fga/modeling/org-roles-and-permissions.mdx
+---
+
+> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=org_roles_permissions), where you can interact with the schema, warrants, and access checks in real-time!
+
+Build a role-based access control (RBAC) that scopes each user's role and permission assignments to a specific organization.
+
+## When to Use it
+
+Implement org roles and permissions when:
+
+- **Role-based access control**: Your application's requirements call for role-based access control (RBAC)
+- **Org-specific roles**: Your customers want to grant their users privileges based on their role within a specific organization.
+
+## Schema
+
+```fga title="schema.txt"
+version 0.3
+
+type user
+
+type organization
+    relation role_admin [user]
+    relation role_read_only [user]
+    inherit role_read_only if
+        relation role_admin
+
+    relation can_read_company_info [role]
+    relation can_write_company_info [role]
+    relation can_read_reports [role]
+    relation can_write_reports [role]
+
+    inherit can_read_company_info if
+        any_of
+            relation can_write_company_info
+            relation role_read_only
+
+    inherit can_write_company_info if
+        relation role_admin
+
+    inherit can_read_reports if
+        any_of
+            relation can_write_reports
+            relation role_read_only
+
+    inherit can_write_reports if
+        relation role_admin
+```
+
+## Example
+
+### (1) Apply the schema
+
+Create a file called `schema.txt` containing the schema definition from above. Then use the CLI to apply this schema to your WorkOS FGA environment.
+
+> Note: make sure to select the correct environment with the [CLI](https://github.com/workos/workos-cli?tab=readme-ov-file#usage)
+
+```shell
+workos fga schema apply schema.txt
+```
+
+---
+
+### (2) Create warrants
+
+Create warrants that associate organizations, roles, and users. The example schema defines the following relationships:
+
+- users with organizations
+- users with custom roles (e.g. `org:acme:read-only`)
+
+Let's create a few warrants between organization `acme`, role `org:acme:read-only`, and user `user_2oDscjroNWtzxzYEnEzT9P7VYEe`:
+
+<CodeBlock
+  title="Create warrants"
+  file="org-roles-permissions-create-warrants"
+/>
+
+---
+
+### (3) Check access
+
+With our environment setup, we can check the user's permission to read company info.
+
+<CodeBlock
+  title="Check if a user has a permission in their organization"
+  file="org-roles-permissions-check"
+/>
+
+---