@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/fga/modeling/public-access.mdx

@@ -1,61 +0,0 @@
----
-title: Public Access
-description: Model public document access using FGA policies.
-originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/public-access.mdx
----
-
-> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=public_access), where you can interact with the schema, warrants, and access checks in real-time!
-
-Public access allows users to view resources without requiring a direct relationship or explicit grant. This is useful for cases where content is meant to be openly accessible but still requires a basic set of conditions, such as being published or flagged as public.
-
-## Example Applications
-
-- **Document Management**: Public reports or documents.
-- **Education Platforms**: Make certain course materials or syllabus open access.
-- **Media & Publishing**: Allow public access to some articles while gating premium ones.
-- **E-Commerce**: Public product listings with private admin dashboards or private draft listings.
-
-## Schema
-
-```fga
-version 0.3
-
-type user
-
-type document
-  relation viewer [user]
-
-  inherit viewer if
-    policy is_public_document
-
-policy is_public_document(document_attributes map) {
-  document_attributes.public == true && document_attributes.status == "published"
-}
-```
-
-> Note: Public access can also be modeled with [wildcard warrants](/fga/warrants/wildcard-warrants). This example focuses on using policies for more control over access conditions.
-
-## 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) Check access
-
-With our environment setup, we can check the user's permission to view a document.
-
-<CodeBlock
-  title="Check if a user can view a document"
-  file="public-access-check"
-/>
-
----

package/.docs/organized/docs/fga/modeling/shareable-content.mdx

@@ -1,106 +0,0 @@
----
-title: Google Docs
-description: >-
-  Build a Google Docs-like authorization model in which users have varying
-  levels of access to documents they can collaborate on with each other.
-originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/shareable-content.mdx
----
-
-> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=google_docs), where you can interact with the schema, warrants, and access checks in real-time!
-
-Implement an authorization model similar to Google Docs document sharing. Allow users to grant read and/or write access to other users on individual documents and folders containing other nested documents and/or folders.
-
-## When to Use it
-
-Consider this authorization model for:
-
-- **User Generated Content**: Your application supports user-generated content (e.g. documents, notes, images, etc.) and users can share access to this content with each other
-- **Collaboration**: You want to allow users to collaborate on content or resources together
-
-## Schema
-
-```fga title="schema.txt"
-version 0.3
-
-type user
-
-type document
-  // Note: folders are modeled as documents.
-  // They can be parents of other documents.
-  relation parent [document]
-  relation role_owner [user]
-  relation role_editor [user]
-  relation role_viewer [user]
-  relation can_write_users []
-  relation can_read_users []
-  relation can_write_content []
-  relation can_read_content []
-
-  inherit role_owner if
-    relation role_owner on parent [document]
-
-  inherit role_editor if
-    any_of
-      relation role_owner
-      relation role_editor on parent [document]
-
-  inherit role_viewer if
-    any_of
-      relation role_editor
-      relation role_viewer on parent [document]
-
-  inherit can_write_users if
-    relation role_owner
-
-  inherit can_read_users if
-    any_of
-      relation role_viewer
-      relation can_write_users
-
-  inherit can_write_content if
-    relation role_editor
-
-  inherit can_read_content if
-    any_of
-      relation role_viewer
-      relation can_write_content
-
-```
-
-## 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 and documents. The example schema defines the following relationships:
-
-- documents with other documents (i.e. folders)
-- users with documents (using one of the defined roles: `owner`, `editor`, or `viewer`)
-
-Let's create a few warrants between documents `doc-1`, `doc-2`, `doc-3`, `folder-1`, `folder-f2`, and user `user_2oDscjroNWtzxzYEnEzT9P7VYEe`:
-
-<CodeBlock title="Create warrants" file="shareable-content-create-warrants" />
-
----
-
-### (3) Check access
-
-With our environment setup, we can check whether the user can read a document's contents.
-
-<CodeBlock
-  title="Check if a user has permission to read a document's contents"
-  file="shareable-content-check"
-/>
-
----

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

@@ -1,74 +0,0 @@
----
-title: Superusers
-description: Learn how to use policies to create superuser overrides.
-originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/superusers.mdx
----
-
-> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=superusers), where you can interact with the schema, warrants, and access checks in real-time!
-
-Superuser policies allow specific users to override inheritance rules to grant broad access to many resources. This is useful for granting elevated privileges to trusted users, such as administrators, support engineers, or internal employees.
-
-## When to Use It?
-
-Use superuser policies when you need to:
-
-- Provide emergency access to a resource without modifying existing permissions.
-- Allow internal employees to manage resources without explicitly assigning them to each one.
-- Implement organization-wide administrative roles that apply across multiple resources.
-
-## Example Applications
-
-Many applications implement superuser policies, including:
-
-- **E-commerce platforms**: Store administrators or support agents need access to all stores for troubleshooting.
-- **Multi-tenant SaaS applications**: Internal employees may need to access any tenant's data for support purposes.
-- **Content management systems**: Superusers may need the ability to edit or review content across multiple projects.
-
-## Schema
-
-```fga
-version 0.3
-
-type user
-
-type store
-  relation editor [user]
-  relation viewer [user]
-
-  // Editors of a store are either
-  //   Assigned directly as an editor of the store
-  //   Or superusers who can edit any store (via is_superuser policy)
-  inherit editor if
-      policy is_superuser
-
-  // Any editor can also view the store
-  inherit viewer if
-    relation editor
-
-policy is_superuser(user_attributes map) {
-  user_attributes.superuser == true &&
-    user_attributes.email endsWith "@internal-domain.com"
-}
-```
-
-## 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) Check access
-
-With our environment setup, we can check the user's permission to view a document.
-
-<CodeBlock title="Check if a user can view a store" file="superusers-check" />
-
----

package/.docs/organized/docs/fga/modeling/user-groups.mdx

@@ -1,92 +0,0 @@
----
-title: User Groups
-description: Learn how to make user group abstractions to manage permissions at scale.
-originalPath: .tmp-workos-clone/packages/docs/content/fga/modeling/user-groups.mdx
----
-
-> Explore the example from this guide [in the FGA Playground](https://explore.fga.workos.com/playground?example=user_groups), where you can interact with the schema, warrants, and access checks in real-time!
-
-User groups in Fine-Grained Authorization (FGA) allow you to manage permissions at scale by grouping users and granting access to those groups. This is particularly useful in large organizations where managing individual user permissions can become cumbersome.
-
-## When to Use It?
-
-You should consider using user groups in the following scenarios:
-
-- **Large Organizations**: When you have a large number of users and resources, managing permissions individually can be inefficient.
-- **Dynamic User Base**: If your user base changes frequently (e.g., employees joining or leaving), management groups can simplify the process of updating permissions.
-- **Hierarchical Structures**: When your organization has a hierarchical structure (e.g., departments, teams), management groups can help you define permissions at different levels of the hierarchy without duplicating effort.
-
-## Example Applications
-
-Management groups can be applied in various scenarios, including:
-
-- **Enterprise Applications**: In large enterprises, you can create groups for different departments (e.g., Sales, Engineering) and assign permissions to these groups rather than individual users.
-- **Multi-Tenant SaaS Applications**: For SaaS applications serving multiple organizations, you can create groups for each tenant and manage permissions for users within those tenants.
-
-## Schema
-
-```fga
-version 0.3
-
-type user
-
-type organization
-  relation admin [user]
-  relation document_viewer [user]
-  relation document_manager [user]
-
-  inherit document_manager if
-    relation admin // admins are also document managers
-
-  inherit document_viewer if
-    relation document_manager // document managers are also viewers
-
-type document
-  // A document has a parent organization
-  relation parent [organization]
-  relation edit [user]
-  relation view [user]
-
-  // Allow users to edit the document if they
-  //  are in the document manager group on the organization that owns it
-  inherit edit if
-    relation document_manager on parent [organization]
-
-  // Allow users to view the document if they
-  //  are in the document viewer group on the organization that owns it
-  inherit view if
-    relation document_viewer on parent [organization]
-```
-
-## 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 and documents. Add a users to a `document_viewer` / `document_manager` groups.
-
-<CodeBlock title="Create warrants" file="user-groups-create-warrants" />
-
----
-
-### (3) Check access
-
-With our environment setup, we can check the user's permission to view items.
-
-<CodeBlock
-  title="Check if a user can view a document"
-  file="user-groups-check"
-/>
-
----

package/.docs/organized/docs/fga/operations-usage.mdx

@@ -1,104 +0,0 @@
----
-title: Operations & Usage
-description: >-
-  Understand the operations_consumed metric and how it can help you optimize
-  your FGA usage.
-showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/fga/operations-usage.mdx
----
-
-WorkOS Fine-Grained Authorization (FGA) empowers developers to design custom authorization models tailored to their specific needs using Access Control Lists (ACLs). In FGA, ACLs can inherit from one another through explicit connections or custom inheritance rules (see [inheritance rules documentation](/fga/schema/schema-syntax/inheritance-rules)). However, the flexibility of these models can complicate capacity planning for FGA quota.
-
-FGA includes the `operations_consumed` metric in select API responses to provide visibility into quota consumption. This metric measures the computational cost of access checks, queries, and warrant transactions, offering developers valuable insights into how their authorization models affect quota usage.
-
-Complex models with deeply nested data or intricate inheritance rules can significantly increase the computational cost of FGA transactions, making it critical to design models thoughtfully. By understanding the impact of these factors, developers can make informed decisions to balance functionality and efficiency.
-
-This article breaks down the purpose of the `operations_consumed` metric, how it works, and strategies for optimizing FGA usage to better manage quota consumption.
-
-## What is `operations_consumed`?
-
-operations_consumed is a metric that quantifies the number of computational operations performed during an ACL check or query in FGA. These operations include sub-tree checks and partial queries that are required to return the response. By tracking this value, FGA provides visibility into quota consumption, enabling developers to:
-
-- Understand the cost of their authorization checks.
-- Optimize their schema for better performance.
-- Ensure efficient usage within the provided quota.
-
-```json title="POST /v1/check"
-{
-  "result": "authorized",
-  "is_implicit": true,
-  "operations_consumed": {
-    "total": 5
-  }
-}
-```
-
-## How Does It Work?
-
-FGA performs access checks by traversing the ACL graph. The ACL graph is defined by warrant connections that are bridged by the inheritance rules defined in your schema. These operations include:
-
-1. **Edge Traversals:** Verifying ACL connectivity through adjacent resources using warrant relations.
-2. **Inheritance Rules:** Evaluating relationships based on inherited connections in your schema.
-3. **Consistency Operations:** Determining whether fully consistent or eventually consistent results are required.
-
-In addition to schema complexity, the number of operations required to evaluate an access check also depends on sub-tree caching. Fully consistent checks inherently rely less on caching than eventually consistent checks. Eventually consistent checks have less strict cache policies, reducing the number of required sub-tree evaluations. However, requests for eventual consistency are not guaranteed to be served from cache. As a result, _`operations_consumed` may vary slightly across requests, with the worst-case scenario involving no caching._
-
-FGA handles cached operations as follows:
-
-- A single access check on cached data always counts as **one operation**.
-- Multiple checks on the same cached result within a single transaction each count as **one operation**.
-- Accessing cached sub-trees avoids evaluating the sub-tree, significantly optimizing query execution.
-
-To optimize both performance and cost, it’s essential to use Warrant Tokens (see [Warrant Token documentation](/fga/warrant-tokens)) effectively and align your schema design with your consistency requirements.
-
-## Implications of Graph Structure
-
-The structure of your ACL graph significantly impacts the operations_consumed metric. Here’s why:
-
-- **Nested Graphs:** While some nesting is acceptable, deeply nested relationships can significantly increase the complexity of access checks. Each additional layer in the graph requires more operations to resolve access, potentially impacting performance and query efficiency.
-
-![FGA diagram showing an ACL graph with nested connections](https://images.workoscdn.com/images/9e3a627d-448a-4769-87e5-1de0ee4b5e10.png?auto=format&fit=clip&q=50)
-
-- **Wide Graphs:** Graphs with many/all resources converging on a single node demand more operations per check to resolve access. As your application grows in size and complexity, more connections may focus on a single node. Performance may degrade and usage could increase.
-
-![FGA diagram showing a wide ACL tree](https://images.workoscdn.com/images/bb30073a-aa9a-41aa-a22a-1c5766d610a0.png?auto=format&fit=clip&q=50)
-
-- **Sparse or Disjoint Graphs:** Sparse graphs, where resources and subjects are minimally connected, consume fewer operations. Disjoint sub-graphs, typically separated by tenant or user, are particularly efficient. Both reduce the traversal scope.
-
-![FGA diagram showing disjoint graphs separated by company identifier](https://images.workoscdn.com/images/2d4610e1-8e4c-44e8-bbfd-fe9f66c49731.png?auto=format&fit=clip&q=50)
-
-## Optimizing operations_consumed Usage
-
-To preserve operations and stay within quota limits, developers can utilize the following strategies:
-
-### Sub-graph Separation
-
-Divide ACLs into smaller, independent sub-graphs. This approach reduces the traversal depth and isolates computational effort to specific areas of the graph. For example, building disjoint sub-graphs for different tenants that use your application.
-
-### Favor Eventual Consistency
-
-Use fully consistent checks only when necessary. Opt for eventually consistent checks to increase the likelihood of cache hits. In practice, developers can avoid fully consistent checks by using Warrant Tokens in API requests.
-
-### Cache Warrant Tokens
-
-Store API-generated Warrant Tokens with atomic writes to reuse them for future access checks, minimizing redundant computations. Cached warrant tokens reduce the need to use fully consistent checks.
-
-### Simplify Relationships
-
-Avoid building a model with unnecessary nesting, complicated inheritance rules, or wide connections. Streamlining relationships minimizes the number of operations required to resolve an access check.
-
-## Why `operations_consumed` Matters
-
-FGA charges based on `operations_consumed` usage, encouraging efficient graph design while providing the flexibility to build robust, scalable access control systems. Key benefits include:
-
-- **Lower Costs:** Reduce quota consumption with optimized graph structures.
-- **Better Performance:** Deliver faster response times for access checks and queries.
-- **Scalability:** Handle larger datasets efficiently without increased resource demands.
-
-By optimizing `operations_consumed`, developers can create cost-effective, high-performing access control models that scale with their applications.
-
-## Testing and Local Development
-
-WorkOS offers an isolated FGA Docker image designed for testing and development. This image utilizes SQLite and in-memory caching and is not intended for production use. It should be used only in a local environment or for running test suites in your CI/CD pipeline.
-
-The fga-dev image is available on our [public ECR repository](https://gallery.ecr.aws/workos/fga-dev). View the `Usage` section for more information about how to use it.

package/.docs/organized/docs/fga/playground.mdx

@@ -1,12 +0,0 @@
----
-title: Playground
-description: >-
-  Use the FGA Playground to explore the capabilities of WorkOS Fine-Grained
-  Authorization.
-showNextPage: true
-originalPath: .tmp-workos-clone/packages/docs/content/fga/playground.mdx
----
-
-The [FGA Playground](https://explore.fga.workos.com/playground) runs in the browser and allows you to interact with the schema, warrants, and queries in real-time before implementing them in your application.
-
-![A screenshot of the FGA Playground](https://images.workoscdn.com/images/d2e7e812-17d0-4607-a0c5-db78a4b86207.png?auto=format&fit=clip&q=50)