@workos/mcp-docs-server 0.1.0 → 0.2.0

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

@@ -1,90 +0,0 @@
----
-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

@@ -1,127 +0,0 @@
----
-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

@@ -1,131 +0,0 @@
----
-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

@@ -1,95 +0,0 @@
----
-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"
-/>
-
----

package/.docs/organized/docs/fga/modeling/policy-context.mdx

@@ -1,231 +0,0 @@
----
-title: Policy Context
-description: Learn how to pass context to policies in FGA.
-originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/policy-context.mdx
----
-
-Policies in FGA allow you to define complex access control rules based on the context of the request. This context can include resource attributes, location and temporal data, or any other relevant information that can help determine access to a specific resource.
-
-This guide will walk you through the process of creating a policy that pulls context in two different ways: check context and injected context.
-
-## When to Use it
-
-Use policy context when:
-
-- **Dynamic Access**: You need to make access decisions based on runtime attributes such as location, time of day, IP address, device type, or authentication method.
-- **Resource Attribute-Based Access**: You want to enforce permissions based on properties of the resource itself such as a course’s level, a document’s classification, or user data.
-- **Complex Policies**: You need to evaluate multiple attributes or conditions together to enforce advanced access rules.
-
-## Check Context
-
-In this approach, you pass context directly in the check request. These values are made available to the policy as named parameters and must be explicitly defined in the policy function signature within your schema.
-
-```fga
-version 0.3
-
-type user
-
-type course
-  relation editor [user]
-  relation viewer [user]
-  relation instructor [user]
-
-  relation edit []
-  relation view_materials []
-  relation moderate_discussion []
-
-  inherit edit if
-    all_of
-      relation editor
-      policy can_edit_course
-      policy has_security_compliance
-
-  inherit view_materials if
-    any_of
-        all_of
-          relation viewer
-          policy can_access_materials
-        relation edit
-
-  inherit moderate_discussion if
-    all_of
-      relation instructor
-      policy can_moderate_discussion
-
-
-policy can_edit_course(check_data map, user_attr map) {
-  check_data.resource_type == "course" &&
-  check_data.resource_id in user_attr.assigned_course_ids &&
-  user_attr.role == "instructor"
-}
-
-policy can_access_materials(user_attr map, course_attr map) {
-  user_attr.is_enrolled == true &&
-  user_attr.org_id == course_attr.org_id
-}
-
-policy can_moderate_discussion(user_attr map, course_attr map) {
-  user_attr.verified == true &&
-  course_attr.discussion_enabled == true &&
-  course_attr.course_level == "advanced"
-}
-
-policy has_security_compliance(security_info map) {
-  security_info.mfa_enabled == true &&
-  date(security_info.last_password_change) > now() - duration("90d")
-}
-```
-
-### (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.
-
-```shell
-workos fga schema apply schema.txt
-```
-
----
-
-### (2) Create warrants
-
-Create warrants that associate users with courses. We'll make a user an editor of a course:
-
-<CodeBlock title="Create warrants" file="policy-context-warrants" />
-
----
-
-### (3) Check access
-
-With our environment setup, we can check the user's permission to `view_materials` on a course.
-
-<CodeBlock
-  title="Check if a user has a permission on a course"
-  file="policy-context-passed-check"
-/>
-
-In this example, the check context includes `check_data`, `user_attr`, `course_attr`, and `security_info`. The policy will evaluate these attributes to determine if the user has access to view materials for the course.
-
-> A drawback with this approach is the size of the context in the check request. This method of passing context requires no state in FGA (other than warrant data), but it starts to break down with complex schemas that require large sets of context data. Consider using injected context for more complex schemas.
-
-## Injected Context
-
-In this method, you can use context injected by the FGA service. Use injected context to fetch resource metadata in your policy so that you don't have to pass it in the check request.
-
-This is useful when your schema requires large context objects, when the context is not known at the time of the check, or when you want to change schemas without updating context in the check request.
-
-Read more about injected context and helper functions in the [policy documentation](/fga/policies/advanced-usage).
-
-```fga
-version 0.3
-
-type user
-
-type course
-  relation editor [user]
-  relation viewer [user]
-  relation instructor [user]
-
-  relation edit []
-  relation view_materials []
-  relation moderate_discussion []
-
-  inherit edit if
-    all_of
-      relation editor
-      policy can_edit_course
-      policy has_security_compliance
-
-  inherit view_materials if
-    any_of
-      all_of
-        relation viewer
-        policy can_access_materials
-      relation edit
-
-  inherit moderate_discussion if
-    all_of
-      relation instructor
-      policy can_moderate_discussion
-
-policy can_edit_course() {
-  let user_metadata = get_metadata(check_ctx.subject_type, check_ctx.subject_id);
-
-  let is_user = check_ctx.subject_type == "user";
-  let is_course = check_ctx.resource_type == "course";
-  let is_assigned = check_ctx.resource_id in user_metadata.assigned_course_ids;
-  let is_instructor = user_metadata.role == "instructor";
-
-  is_user && is_course && is_assigned && is_instructor
-}
-
-policy can_access_materials() {
-  let user_metadata = get_metadata(check_ctx.subject_type, check_ctx.subject_id);
-  let course_metadata = get_metadata(check_ctx.resource_type, check_ctx.resource_id);
-
-  let is_user = check_ctx.subject_type == "user";
-  let is_enrolled = user_metadata.is_enrolled == true;
-  let same_org = user_metadata.org_id == course_metadata.org_id;
-
-  is_user && is_enrolled && same_org
-}
-
-policy can_moderate_discussion() {
-  let user_metadata = get_metadata(check_ctx.subject_type, check_ctx.subject_id);
-  let course_metadata = get_metadata(check_ctx.resource_type, check_ctx.resource_id);
-
-  let is_user = check_ctx.subject_type == "user";
-  let is_verified = user_metadata.verified == true;
-  let discussion_enabled = course_metadata.discussion_enabled == true;
-  let is_advanced = course_metadata.course_level == "advanced";
-
-  is_user && is_verified && discussion_enabled && is_advanced
-}
-
-policy has_security_compliance() {
-  let user_metadata = get_metadata(check_ctx.subject_type, check_ctx.subject_id);
-
-  let is_user = check_ctx.subject_type == "user";
-  let mfa_enabled = user_metadata.mfa_enabled == true;
-  let recent_password = date(user_metadata.last_password_change) > now() - duration("90d");
-
-  is_user && mfa_enabled && recent_password
-}
-```
-
-### (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.
-
-```shell
-workos fga schema apply schema.txt
-```
-
----
-
-### (2) Create warrants
-
-Create warrants that associate users with courses. We'll make a user an editor of a course:
-
-<CodeBlock title="Create warrants" file="policy-context-warrants" />
-
----
-
-### (3) Update app code to sync resource metadata
-
-In order to pull resource metadata from our policies, we need to update our app code to sync resource metadata with the FGA service. This is done by calling the [update resource](/reference/fga/resource/update) endpoint in the FGA API.
-
-<CodeBlock
-  title="Update resource metadata"
-  file="policy-context-update-metadata"
-/>
-
----
-
-### (4) Check access
-
-With our environment setup, we can check the user's permission to `view_materials` on a course.
-
-<CodeBlock
-  title="Check if a user has a permission on a course"
-  file="policy-context-injected-check"
-/>