@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/fga/resource-types.mdx

@@ -0,0 +1,165 @@
+---
+title: Resource Types
+description: >-
+  Define the schema of your application's resource hierarchy in the WorkOS
+  Dashboard.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/resource-types.mdx
+---
+
+## Introduction
+
+Before your application can manage fine-grained access, you need to define what kinds of objects exist in your product. Resource types are that schema—they describe the categories of entities users interact with and how those entities relate to each other.
+
+Most B2B applications have a natural hierarchy. Users belong to organizations, organizations contain workspaces, workspaces contain projects, and projects contain apps. Resource types let you formalize this structure so FGA can evaluate permissions at any level.
+
+Resource types are configured in the [WorkOS Dashboard](https://dashboard.workos.com/) rather than through code, ensuring your authorization schema is intentionally designed and easy to update as your product evolves.
+
+---
+
+## What makes a resource type
+
+A resource type represents a category of business entity—something users create, access, and collaborate on. Common examples include workspaces, projects, applications, repositories, and dashboards.
+
+Each resource type has a few properties:
+
+**Name** is the display name users see in the Dashboard, like "Workspace" or "Project."
+
+**Slug** is the URL-safe identifier used in API calls, like `workspace` or `project`. Choose slugs that are lowercase, concise, and match your product terminology.
+
+**Description** is optional text explaining what this type represents in your application.
+
+**Parent types** define which resource types can be parents in the hierarchy. A project might have `workspace` as a parent type, while a workspace might have `organization` as its only parent.
+
+---
+
+## Designing your hierarchy
+
+Start by mapping your existing product structure. Think about the entities users create and how they're nested:
+
+```text
+organization (implicit root)
+└─ workspace
+   └─ project
+      └─ app
+```
+
+Organizations are always the root—every hierarchy starts there. Below that, you define the types that make sense for your product.
+
+When deciding what to model as a resource type, ask whether users can have different access levels to different instances. If all projects in a workspace have the same access, you might not need `project` as a separate type. If users can be an admin on one project but only a viewer on another, that's a strong signal to model it.
+
+Keep your hierarchy shallow—aim for 2-4 levels. Deep hierarchies are harder to understand and manage, both for you and your customers.
+
+---
+
+## Examples for different products
+
+**Multi-tenant SaaS platform**: Organizations contain workspaces, workspaces contain projects, and projects contain apps and databases. Customers create workspaces for different teams, with projects organizing their actual work.
+
+```text
+organization
+└─ workspace
+   └─ project
+      ├─ app
+      └─ database
+```
+
+**Developer platform**: Organizations directly contain repositories, and repositories own branches and secrets. Access is granted at the repository level, with branches and secrets inheriting from their parent repository.
+
+```text
+organization
+└─ repository
+   ├─ branch
+   └─ secret
+```
+
+**Analytics application**: Organizations contain accounts, and accounts contain multiple dashboards. Each dashboard might have different access levels for different stakeholders.
+
+```text
+organization
+└─ account
+   └─ dashboard
+```
+
+**AI agent platform**: Organizations contain workspaces, and workspaces contain AI agents, the tools those agents can invoke, and the datasets they access. Users need different levels of access to different agents, and agents themselves need scoped permissions to specific tools and datasets—an agent in one workspace might invoke a search tool and read customer data, while another agent is limited to internal documentation.
+
+What makes this hierarchy distinct is that agents are both resources and subjects. As resources, they live inside workspaces and users control who can configure or launch them. As subjects, agents receive role assignments on tools and datasets just like users do—an agent might have `invoker` on `tool:web-search` and `reader` on `dataset:customers`. When an agent acts on behalf of a user, it should only receive a subset of that user's access, never more.
+
+```text
+organization
+└─ workspace
+   ├─ agent
+   ├─ tool
+   └─ dataset
+```
+
+---
+
+## Hierarchy rules
+
+A few constraints help keep your authorization model predictable:
+
+**Maximum depth** is five levels, which covers even complex enterprise products. Most applications need only two or three.
+
+**Single parent** means each resource instance has exactly one parent. A project belongs to one workspace, not multiple.
+
+**Multiple parent types** let a resource type accept different parents. An `app` might be created directly under a workspace or nested under a project, so both would be valid parent types.
+
+These constraints exist to keep permission evaluation fast and predictable. Single-parent hierarchies ensure that inherited permissions always flow through a clear path—there's no ambiguity about which parent's roles apply. The depth limit keeps traversal efficient and prevents authorization models from becoming unwieldy.
+
+That said, the five-level depth limit is a soft limit based on typical enterprise patterns, not a technical limitation. If your use case requires deeper hierarchies, [reach out to us](https://workos.com/contact) to discuss your specific needs.
+
+---
+
+## Creating and managing resource types
+
+Resource types are managed exclusively through the [WorkOS Dashboard](https://dashboard.workos.com/)—they cannot be created, modified, or deleted via the public API.
+
+Resource types define your authorization schema, and changes to them can have far-reaching consequences: altering a parent relationship affects how permissions inherit, removing a type orphans all its resources and role assignments, and changing the hierarchy can break application logic that depends on it. By restricting resource type management to the Dashboard, we ensure these changes are made deliberately by someone reviewing the full impact, not accidentally by a script or misconfigured automation.
+
+### Using the Dashboard
+
+Navigate to **Resources Types** under **Authorization** to configure resource types for your environment. The resource type editor provides:
+
+- **Visual hierarchy builder** to arrange parent-child relationships
+- **Type configuration** for names, slugs, and descriptions
+- **Relationship validation** that ensures hierarchy constraints are met before saving
+
+![FGA resource types page](https://images.workoscdn.com/images/b38cad2f-8d61-42d3-aacf-577d24621b5c.png?auto=format&fit=clip&q=50)
+
+To create a new resource type, click **Edit resource types**, provide a name and slug, and configure which types can be parents. The Dashboard shows how the new type fits into your existing hierarchy.
+
+![FGA edit resource types page](https://images.workoscdn.com/images/c710ca31-044c-429a-84dd-6d660ab50277.png?auto=format&fit=clip&q=50)
+
+### Modifying resource types
+
+Once a resource type exists, you can update its name and description freely—these are display values that don't affect API behavior. However, slugs cannot be changed after creation. They're used in API calls, and changing them would break existing integrations. If you need a different slug, create a new resource type and migrate your resources.
+
+> Support for adding parent types is coming soon.
+
+### Removing resource types
+
+Before removing a resource type:
+
+1. Remove any roles and permissions scoped to that type (deleting a role automatically removes its assignments)
+2. Ensure no child types depend on it—only leaf types can be deleted
+
+Once these dependencies are resolved, deleting the resource type from the Dashboard will automatically clean up all resource instances of that type.
+
+---
+
+## Adding types as you grow
+
+One of the goals of FGA is to make it easy to evolve your authorization model as your product grows. Unlike other systems where changing inheritance rules or adding new entity types requires rewriting complex policies, FGA lets you add new resource types without disrupting existing access patterns.
+
+When you ship a new feature that needs its own access control—say, deployments for your developer platform—you simply add a `deployment` resource type and define its parent relationship. Existing types, roles, and assignments continue working unchanged.
+
+```text
+organization
+└─ workspace
+   ├─ repository
+   ├─ pipeline
+   └─ deployment (new feature)
+```
+
+You don't need to predict every future resource type upfront. Start with the types you need today, and add more as you build new features. The hierarchy is designed to grow with your product.

package/.docs/organized/docs/fga/resources.mdx

@@ -1,92 +1,212 @@
 ---
 title: Resources
-description: >-
-  Resources are FGA's references to your application's access controlled
-  resources.
+description: Represent your application's entities in the FGA hierarchy.
 showNextPage: true
 originalPath: .tmp-workos-clone/packages/docs/content/fga/resources.mdx
 ---
 
-FGA stores a set of warrants representing relationships between _resources_ in an application. These resources are typically application-specific objects persisted in the application's datastore (e.g. MySQL, PostgreSQL, MongoDB, etc). In FGA, they are referred to as _resources_.
+## Introduction
 
-## Overview
+Resources are the runtime counterpart to resource types. While resource types define your schema, resources represent the actual instances users create and work with.
 
-```shell
-      report    :    balance-sheet
-        |                  |
-   Resource Type      Resource ID
+When a user creates a workspace in your application, you register a corresponding resource in WorkOS. When they create a project inside that workspace, you register another resource as a child of the workspace. This builds the hierarchy that FGA uses to evaluate permissions.
+
+Each resource has a type, an external ID from your application, a parent (the organization or another resource), and a human-readable name. Together, these form the tree structure where access is assigned and inherited.
+
+---
+
+## Organization resources
+
+An organization resource is automatically created for every organization in WorkOS and serves as the root of your hierarchy. Organization resources cannot be edited or deleted—they exist for the lifetime of the organization.
+
+Every resource you create must have a parent. For top-level resources like workspaces, the parent is the organization resource. You can reference it using the organization's ID directly as the external ID.
+
+---
+
+## Creating resources
+
+Register resources as users create entities in your application. For top-level resources like workspaces, the parent is optional — when omitted, the resource defaults to the organization as its parent:
+
+```bash
+curl https://api.workos.com/authorization/resources \
+  -X POST \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "resource_type_slug": "workspace",
+    "external_id": "workspace_01H",
+    "organization_id": "org_01HXYZ",
+    "name": "Engineering"
+  }'
 ```
 
-Resources consist of three attributes:
+For nested resources, specify the parent to establish the hierarchy. You can reference the parent by its internal WorkOS ID:
+
+```bash
+curl https://api.workos.com/authorization/resources \
+  -X POST \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "resource_type_slug": "project",
+    "external_id": "project_02H",
+    "organization_id": "org_01HXYZ",
+    "parent_resource_id": "authz_resource_01HXYZ",
+    "name": "API Backend"
+  }'
+```
 
-- **Resource Type** - Specifies what _type_ of entity a particular resource is (e.g. a user, a tenant, a report, etc).
-- **Resource ID** - Specifies a unique identifier for the resource (typically the same unique identifier used in your application to identify the resource).
-- **Meta** (optional) - A JSON object containing additional data related to the resource that it would be helpful for FGA to know about (e.g. a user's email address, a tenant's display name, a description of the privileges a role grants, etc).
+Or reference the parent by its external ID and type, which is often more convenient since you're already tracking your own entity IDs:
+
+```bash
+curl https://api.workos.com/authorization/resources \
+  -X POST \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "resource_type_slug": "project",
+    "external_id": "project_02H",
+    "organization_id": "org_01HXYZ",
+    "parent_resource_type_slug": "workspace",
+    "parent_resource_external_id": "workspace_01H",
+    "name": "API Backend"
+  }'
+```
 
-Resources make it easier to manage the warrants associated with each resource, providing a way for applications to persist authorization-specific data outside of (or often, in lieu of) their primary datastore.
+See the [API reference](/reference) for full endpoint documentation.
 
-## Creating and Managing Resources
+---
 
-FGA automatically creates the resources that are referenced by warrants when they are created. This means developers using FGA don't need to worry about manually creating resources.
+## External IDs
 
-For example, given the following warrant:
+External IDs are your application's identifiers for resources—typically the primary key from your database. They provide a stable reference that maps directly to your records.
 
-```json title="report:balance-sheet#editor@user:john-doe"
-{
-  "resource_type": "report",
-  "resource_id": "balance-sheet",
-  "relation": "editor",
-  "subject": {
-    "resource_type": "user",
-    "resource_id": "john-doe"
-  }
-}
+External IDs must be unique within a resource type and organization. Two workspaces in the same organization can't share an external ID, but a workspace and a project can (since they're different types). Two workspaces in different organizations can also share an external ID.
+
+This uniqueness rule simplifies resource management for managed service providers and platforms that provision similar structures for each customer. Every customer might have a "main" workspace with external ID `main`—that's fine because they're in different organizations.
+
+Use your existing database IDs or UUIDs for external IDs. Keep them stable—don't change an ID after creation—and choose values that are meaningful for debugging and support.
+
+### Managing resources by external ID
+
+Beyond using internal WorkOS resource IDs, you can manage resources directly using your external IDs:
+
+```bash
+# Get a resource by external ID
+curl "https://api.workos.com/authorization/organizations/org_01HXYZ/resources/workspace/workspace_01H" \
+  -H "Authorization: Bearer sk_example_123456789"
+
+# Update a resource by external ID
+curl https://api.workos.com/authorization/organizations/org_01HXYZ/resources/workspace/workspace_01H \
+  -X PATCH \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{ "name": "Engineering Team" }'
+
+# Delete a resource by external ID
+curl https://api.workos.com/authorization/organizations/org_01HXYZ/resources/workspace/workspace_01H \
+  -X DELETE \
+  -H "Authorization: Bearer sk_example_123456789"
 ```
 
-FGA will automatically create two resources upon creation of the warrant:
+This is often more convenient than looking up internal resource IDs since you're already tracking your own entity IDs.
+
+---
+
+## Keeping resources in sync
+
+Resources should mirror your application's data. When entities are created, updated, or deleted in your app, the corresponding resources should change in WorkOS.
+
+**On creation**, register the resource immediately after saving the entity to your database. The resource needs to exist before you can assign roles to it.
+
+**On deletion**, remove the resource when the entity is deleted. By default, deleting a resource will fail if it has child resources or role assignments. Pass `cascade_delete=true` to delete the resource along with all its children and their role assignments.
+
+**On rename**, update the resource's name when the entity's name changes in your application. External IDs and parent relationships are immutable after creation.
 
-```json title="report:balance-sheet"
+> Support for changing parent relationships is coming soon.
+
+---
+
+## What to model as resources
+
+FGA is optimized for low-cardinality, stable entities—the structural elements of your application where access boundaries matter.
+
+**Good candidates for FGA resources**: Workspaces, teams, accounts, projects, repositories, pipelines, dashboards, environments—entities where users have different access levels to different instances, and the count is typically in the hundreds to thousands per organization.
+
+**Keep in your database**: Documents, messages, tasks, files, comments, rows—high-volume content that changes frequently and typically inherits access from a parent. Modeling millions of documents as individual resources would overwhelm sync and provide no real benefit.
+
+As a rule of thumb, hundreds to thousands of resources per organization works well. Tens of thousands might work but consider whether they all need individual access control. Millions should stay in your database with references to their parent FGA resource.
+
+FGA has a **soft limit of 5,000 resource instances per resource type per organization.** This is based on our experience working with customers to avoid potential data syncing issues—not a technical limitation. If your use case requires higher cardinality, [reach out to us](https://workos.com/contact) to discuss your specific needs.
+
+## Parent references for high-volume data
+
+High-volume entities can participate in authorization without being modeled as FGA resources. Store a reference to the nearest FGA-managed parent in your database:
+
+```json
 {
-  "resource_type": "report",
-  "resource_id": "balance-sheet"
+  "id": "doc_abc123",
+  "content": "...",
+  "project_id": "proj_456" // ← Reference to FGA resource
 }
 ```
 
-```json title="user:john-doe"
-{
-  "resource_type": "user",
-  "resource_id": "john-doe"
-}
+When checking access, ask about the parent:
+
+```bash
+# Can this user edit this document?
+# → Check: Does user have document:edit on Project proj_456?
+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": "document:edit",
+    "resource_type_slug": "project",
+    "resource_external_id": "proj_456"
+  }'
 ```
 
-Resources can be managed from the [FGA Dashboard](https://fga.workos.com) and/or via API. Refer to the [Resources API Reference](/reference/fga/resource/create) to learn more about managing resources via API.
+This approach keeps authorization fast (no sync lag), avoids reconciliation issues, scales to millions of documents, and uses the existing permission hierarchy. Users with `document:edit` on the project can edit all documents in it without syncing each document to WorkOS.
+
+---
 
-> When a resource is deleted, any warrants associated with the resource will automatically be deleted. This makes it easier for applications to remove all warrants associated with a resource when the resource is deleted from the application itself.
+## Querying resources
 
-## Metadata
+List resources with optional filters:
 
-Resources can be augmented with additional authorization-specific metadata (e.g. the display name for a role or permission, the description of a particular feature, etc). Metadata is especially useful when implementing permission-specific user interfaces. For example, when building a customer-facing page for managing team-level roles and permissions, metadata can provide user-friendly names and descriptions of what actions/resources each role or permission will grant to a user.
+```bash
+curl "https://api.workos.com/authorization/resources?resource_type_slug=project&organization_id=org_01HXYZ" \
+  -H "Authorization: Bearer sk_example_123456789"
+```
 
-```json title="user:john-doe w/ metadata"
-{
-  "resource_type": "user",
-  "resource_id": "john-doe",
-  "meta": {
-    "email": "john-doe@acme-corp.com",
-    "isActivated": true
-  }
-}
+Get a specific resource:
+
+```bash
+curl https://api.workos.com/authorization/resources/authz_resource_01HXYZ \
+  -H "Authorization: Bearer sk_example_123456789"
 ```
 
-```json title="role:accountant w/ metadata"
-{
-  "resource_type": "role",
-  "resource_id": "accountant",
-  "meta": {
-    "name": "Accountant",
-    "description": "Allows a user to view the financial reporting pages and edit charges."
-  }
-}
+See the [API reference](/reference) for full query parameters.
+
+---
+
+## Updating and deleting
+
+Update a resource's name when the corresponding entity changes:
+
+```bash
+curl https://api.workos.com/authorization/resources/authz_resource_01HXYZ \
+  -X PATCH \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{ "name": "Engineering Team" }'
 ```
 
-> There is a 50kb limit on the size of the metadata object.
+Delete a resource when the entity is deleted from your application. By default, the request will fail if the resource has child resources or role assignments. Pass `cascade_delete=true` to remove the resource along with all its children and their assignments:
+
+```bash
+curl "https://api.workos.com/authorization/resources/authz_resource_01HXYZ?cascade_delete=true" \
+  -X DELETE \
+  -H "Authorization: Bearer sk_example_123456789"
+```

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

@@ -0,0 +1,122 @@
+---
+title: Roles and Permissions
+description: Define what users can do within specific resource types.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/roles-and-permissions.mdx
+---
+
+## Introduction
+
+Once you've defined your resource types, the next step is deciding what users can actually do. Roles and permissions in FGA are always scoped to a specific resource type—a workspace role applies only to workspaces, a project role applies only to projects.
+
+This scoping makes permissions predictable. When you see `workspace-admin`, you know it grants workspace access. When a role includes permissions for child types, those permissions flow down automatically—a workspace admin can access all projects in that workspace without separate assignments.
+
+---
+
+## Understanding permissions
+
+A permission represents a specific action a user can perform on a resource type. Each permission has a name (like "Edit Workspace"), a slug used in code (`workspace:edit`), and the resource type it applies to.
+
+We recommend following a `{resource_type}:{action}` pattern for permission slugs. This makes permissions self-documenting—`project:delete` clearly means the ability to delete a project.
+
+Common patterns include:
+
+- `{type}:view` for read access
+- `{type}:edit` for modifying a resource
+- `{type}:create` for creating child resources
+- `{type}:delete` for removing a resource
+- `{type}:manage` for full administrative control
+- `{type}:invite` for adding collaborators
+
+Keep permissions granular. Instead of a broad `project:access` permission, create specific ones like `project:view`, `project:edit`, and `project:delete`. This gives you flexibility as your product's access requirements evolve.
+
+---
+
+## Understanding roles
+
+Roles are collections of permissions that describe what someone can do. Like permissions, each role is scoped to a resource type—you create a role for workspaces, another for projects, and so on.
+
+We recommend naming roles to indicate both the scope and the capability level. Following a `{resource-type}-{capability}` pattern makes roles self-explanatory:
+
+- `workspace-admin` – full control of a workspace
+- `workspace-member` – basic workspace access
+- `project-editor` – can modify a project
+- `project-viewer` – read-only project access
+
+When you assign `workspace-admin` to a user on a specific workspace, they get all the permissions bundled in that role for that workspace.
+
+---
+
+## Permission inheritance
+
+The key feature of FGA roles is that they can include permissions for child resource types. This is where the power of hierarchical authorization comes in.
+
+A `workspace-admin` role might include:
+
+- `workspace:view` and `workspace:edit` (same type)
+- `project:view` and `project:edit` (child type)
+- `app:view` and `app:deploy` (grandchild type)
+
+When you assign this role to someone on a workspace, they can view and edit that workspace, plus view, edit, and deploy all projects and apps within it. One assignment grants access across the entire sub-tree.
+
+This reduces "role explosion"—instead of creating separate roles for every resource combination, you define roles at appropriate levels and let inheritance handle the rest. A workspace admin naturally has access to everything in the workspace, which matches how people think about access.
+
+---
+
+## Seeing inheritance in action
+
+To understand how permission inheritance works in practice, consider a hierarchy where an organization contains projects, and projects contain apps:
+
+```text
+Org
+  └─ Project
+        └─ App
+```
+
+Different users can have roles at different levels, and the access they receive depends on where their role is assigned and what permissions that role includes.
+
+![Example resource hierarchy with roles](https://images.workoscdn.com/images/74c1fad7-abe9-4c21-a244-8c2563f1313c.png?auto=format&fit=clip&q=50)
+
+- User John has `Project read-only` on `Project:1` and can view only that project, not its apps
+
+- User Jane is `Org member` of `Org:1` with `org:read`, `project:read`, and `app:read` permissions. They can view the organization, all of its projects, and all apps under those projects.
+
+- Jane is also `Project editor` for `Project:2` and can read and edit `Project:2` and all of its apps.
+
+- Jane has `App editor` for `App:Finance` and can view and edit only that app instance.
+
+This pattern is powerful because it lets you express nuanced access with minimal assignments. A single organization-level membership provides baseline visibility, while targeted assignments grant elevated access where needed. The hierarchy does the work of propagating permissions, so you don't have to create individual assignments for every resource.
+
+---
+
+## How access is evaluated
+
+When your application checks whether a user can perform an action on a resource, FGA looks at all possible sources of access:
+
+1. **Direct assignments** on the resource itself
+2. **Inherited assignments** from parent resources
+3. **Organization-level roles** that include the permission
+
+If any of these grant the permission, the user is authorized.
+
+For example, if Alice wants to deploy `App:Frontend`, FGA checks whether she has `app:deploy` directly on that app, or on its parent project, or on its parent workspace, or through an organization role. Her `workspace-admin` role on `Workspace: Engineering` includes `app:deploy`, so she's authorized—even without any direct assignment on the app.
+
+Permissions are additive. If a user has multiple roles, they get the union of all permissions from all their roles. There's no way for one role to remove permissions granted by another.
+
+---
+
+## Managing roles in the Dashboard
+
+Configure roles and permissions in the [WorkOS Dashboard](https://dashboard.workos.com/) under **Authorization**. You'll need to have [resource types](/fga/resource-types) defined before you can create scoped roles and permissions.
+
+To create a new role, select the resource type it applies to and give it a descriptive name and slug.
+
+![FGA create role set details](https://images.workoscdn.com/images/9e943b39-8c7f-448a-8568-2408402d2873.png?auto=format&fit=clip&q=50)
+
+Then choose which permissions to include from the same type and child types.
+
+![FGA create role assign permissions](https://images.workoscdn.com/images/98c6a8b5-8814-49d9-a27f-9ba32525c214.png?auto=format&fit=clip&q=50)
+
+When you modify a role's permissions, changes apply immediately to everyone with that role. No re-assignment is needed—existing users automatically get the updated permissions.
+
+For organizations using [multiple roles](/authkit/roles-and-permissions/multiple-roles), users receive all permissions from all their assigned roles. Priority order only matters for [IdP role assignment](/fga/idp-role-assignment) when running in single-role mode.