@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/fga/quick-start.mdx

@@ -1,174 +1,359 @@
 ---
 title: Quick Start
 description: >-
-  Set up resource types and warrants that model your authorization requirements.
-  Then use the SDK to make access checks from your application.
+  Build a complete authorization model from resource types to access checks in
+  minutes.
+showNextPage: true
 originalPath: .tmp-workos-clone/packages/docs/content/fga/quick-start.mdx
 ---
 
-## Before getting started
+## What you'll build
 
-To get the most out of this guide, you should have:
+This guide walks you through the entire FGA workflow using a real-world example: a project management application where organizations contain workspaces, and workspaces contain projects. By the end, you'll have:
 
-- A [WorkOS account](https://dashboard.workos.com/)
-- Your WorkOS [API Key](/glossary/api-key)
-- A basic understanding of [resource types](/fga/schema/schema-syntax/resource-types)
+- A resource type hierarchy modeled in the Dashboard
+- Roles and permissions scoped to each resource type
+- Resources registered via the API
+- Role assignments granting users access
+- Access checks verifying permissions
+- Discovery queries listing accessible resources
 
-## What you'll build
+The guide follows the same order you'd use when integrating FGA into your product.
 
-In this guide, we'll implement fine-grained authorization for a simple B2B SaaS application that gives users the ability to build and share reports generated using company data.
+---
 
-We will:
+## 1. Configure resource types
 
-1. Design a resource type schema that models the application's authorization requirements.
-2. Create warrants to define relationships between the application's resources.
-3. Make access checks that determine whether or not a user should have access to a resource.
+Resource types define the schema of your authorization model. Start by mapping your product's entity hierarchy in the [WorkOS Dashboard](https://dashboard.workos.com/).
 
-## API resource definitions
+For our project management app, the hierarchy looks like:
 
-[Schema](/fga/schema)
-: A schema defining the different types of relationships available on your application's resources and how those relationships can be inherited
+```text
+organization (implicit root)
+└─ workspace
+   └─ project
+```
 
-[Warrant](/fga/warrants)
-: A rule assigning a relationship between two resources in your application
+Navigate to **Authorization > Resource Types** and click **Model resource types**.
 
-## (1) Install the WorkOS CLI
+![FGA model resource types](https://images.workoscdn.com/images/131f0723-6185-4641-946d-e713eec118d1.png?auto=format&fit=clip&q=50)
 
-Install the WorkOS CLI using [Homebrew](https://brew.sh/).
+Create the `workspace` resource type first. Give it a name, a slug, and set its parent to `organization`. Then create `project` with its parent set to `workspace`.
 
-```shell
-brew install workos/tap/workos-cli
-```
+![FGA project resource type](https://images.workoscdn.com/images/a4b3fc33-b6f6-4f0e-a0b7-0d5309ab32a9.png?auto=format&fit=clip&q=50)
 
-To initialize the CLI, use the command below. Follow the prompts to complete setup.
+The Dashboard validates your hierarchy as you build it, ensuring constraints like single-parent relationships and maximum depth are respected.
 
-```shell
-workos init
-```
+---
+
+## 2. Create roles and permissions
+
+With resource types defined, create the roles and permissions that describe what users can do. Navigate to **Authorization > Permissions** in the Dashboard.
+
+### Define permissions
+
+Permissions represent specific actions on a resource type. We recommend a `{resource_type}:{action}` naming pattern.
+
+Navigate to **Authorization > Permissions** and click **Create permission**. Select the resource type the permission applies to, give it a name and slug, and save.
+
+![FGA workspace viewer permission](https://images.workoscdn.com/images/2b656ec6-9391-4a0a-919e-7f31ffb6311a.png?auto=format&fit=clip&q=50)
+
+Create the following permissions for our example:
+
+| Permission       | Resource Type | Description                    |
+| ---------------- | ------------- | ------------------------------ |
+| `workspace:view` | workspace     | View a workspace               |
+| `workspace:edit` | workspace     | Edit workspace settings        |
+| `project:view`   | project       | View a project                 |
+| `project:edit`   | project       | Edit a project                 |
+| `project:create` | project       | Create projects in a workspace |
+| `project:delete` | project       | Delete a project               |
+
+### Define roles
+
+Roles bundle permissions and are scoped to a resource type. The key feature is that roles can include permissions for child types, enabling inheritance.
+
+Create a `workspace-admin` role scoped to the `workspace` resource type. Include permissions for the workspace itself and its child types:
+
+![FGA create role set details](https://images.workoscdn.com/images/9e943b39-8c7f-448a-8568-2408402d2873.png?auto=format&fit=clip&q=50)
+
+Select which permissions to include—both same-type and child-type permissions:
+
+![FGA create role assign permissions](https://images.workoscdn.com/images/98c6a8b5-8814-49d9-a27f-9ba32525c214.png?auto=format&fit=clip&q=50)
+
+Here's a useful set of roles for our example:
+
+| Role               | Scoped to | Permissions included                                                                                   |
+| ------------------ | --------- | ------------------------------------------------------------------------------------------------------ |
+| `workspace-admin`  | workspace | `workspace:view`, `workspace:edit`, `project:view`, `project:edit`, `project:create`, `project:delete` |
+| `workspace-member` | workspace | `workspace:view`, `project:view`                                                                       |
+| `project-editor`   | project   | `project:view`, `project:edit`                                                                         |
+| `project-viewer`   | project   | `project:view`                                                                                         |
+
+A `workspace-admin` assignment on a single workspace grants access to all projects within it. A `project-editor` assignment grants access to only that specific project. This layered approach minimizes the number of assignments you need to manage.
 
 ---
 
-## (2) Define a resource type schema
+## 3. Create resources
+
+Resources are runtime instances of your resource types. Register them via the API as users create entities in your application.
+
+### Top-level resources
+
+When a user creates a workspace, register it as a resource. Top-level resources default to the organization as their parent:
 
-Our application has three types of resources: reports, teams, and users. Our authorization model should meet the following requirements:
+```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"
+  }'
+```
 
-- Every report belongs to a team.
-- Every user belongs to a team.
-- Users who create a report are considered the owner of the report.
-- The owner of a report can also edit the report.
-- The owner of a report can add other users as editors.
-- An editor of a report can also view the report.
-- Users can view any report belonging to their team.
+Response:
+
+```json
+{
+  "id": "authz_resource_01HABC",
+  "resource_type_slug": "workspace",
+  "external_id": "workspace_01H",
+  "organization_id": "org_01HXYZ",
+  "name": "Engineering",
+  "parent_resource_id": null,
+  "created_at": "2025-01-15T10:30:00Z",
+  "updated_at": "2025-01-15T10:30:00Z"
+}
+```
 
-We'll define the following resource type schema to fulfill these requirements:
+The `external_id` is your application's identifier for this entity—typically the primary key from your database. Use it to reference this resource in future API calls without needing to store the WorkOS resource ID.
+
+### Child resources
+
+When a user creates a project inside a workspace, register it with a parent reference. You can reference the parent by its external ID and type:
+
+```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"
+  }'
+```
 
-```fga title="schema.txt"
-version 0.3
+Or 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_03H",
+    "organization_id": "org_01HXYZ",
+    "parent_resource_id": "authz_resource_01HABC",
+    "name": "Mobile App"
+  }'
+```
 
-type user
+Register resources immediately after saving the entity to your database. The resource needs to exist in WorkOS before you can assign roles or check permissions on it.
 
-type team
-  relation member [user]
+---
+
+## 4. Assign roles
 
-type report
-  relation parent [team]
-  relation owner [user]
-  relation editor [user]
-  relation viewer [user]
+Assignments connect a user (through their organization membership) to a role on a specific resource. This is what actually grants access.
 
-  inherit editor if
-    relation owner
+### Assign a workspace role
 
-  inherit viewer if
-    any_of
-      relation editor
-      relation member on parent [team]
+Give Alice (`om_01HXYZ`) the `workspace-admin` role on the Engineering workspace:
 
+```bash
+curl https://api.workos.com/authorization/organization_memberships/om_01HXYZ/role_assignments \
+  -X POST \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "role_slug": "workspace-admin",
+    "resource_type_slug": "workspace",
+    "resource_external_id": "workspace_01H"
+  }'
 ```
 
-### (A) Using the CLI
+Because `workspace-admin` includes child-type permissions like `project:view` and `project:edit`, Alice now has access to all projects within the Engineering workspace—without needing separate assignments on each project.
+
+### Assign a resource-specific role
 
-Create a file called `schema.txt` containing the schema definition from above. Then use the CLI to update your schema in WorkOS FGA.
+Give Bob the `project-editor` role on just the API Backend project:
 
-```shell
-workos fga schema apply schema.txt
+```bash
+curl https://api.workos.com/authorization/organization_memberships/om_02HXYZ/role_assignments \
+  -X POST \
+  -H "Authorization: Bearer sk_example_123456789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "role_slug": "project-editor",
+    "resource_type_slug": "project",
+    "resource_external_id": "project_02H"
+  }'
 ```
 
-### (B) Using the FGA Dashboard
+Bob can view and edit the API Backend project, but has no access to other projects in the workspace unless separately assigned.
 
-Define a resource type schema from the FGA dashboard using the schema editor available on the [Schema](https://fga.workos.com/schema) page.
+### View assignments in the Dashboard
+
+Navigate to an organization membership in the Dashboard to see all role assignments for that user:
+
+![FGA assignments](https://images.workoscdn.com/images/c9a27787-a97c-4e8b-ac86-05cba25374ae.png?auto=format&fit=clip&q=50)
 
 ---
 
-## (3) Create warrants
+## 5. Check permissions
 
-Warrants are rules that assign relationships between the resources in an application. These relationships are then used to figure out whether or not a user should have access to a resource.
+Access checks answer: "Can this user perform this action on this resource?" FGA evaluates all possible sources of access—direct assignments, inherited permissions from parent resources, and organization-level roles.
 
-For example, let's create two warrants:
+### Check by resource external ID
 
-- One specifying that `[user:d6ed6474-784e-407e-a1ea-42a91d4c52b9] is a [member] of [team:stark]`
-- One specifying that `[team:stark] is [parent] of [report:7]`
+Check whether Alice (`om_01HXYZ`) can edit the API Backend project:
 
-### (A) Using the CLI
+```bash
+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": "project:edit",
+    "resource_type_slug": "project",
+    "resource_external_id": "project_02H"
+  }'
+```
 
-Create warrants using the CLI.
+Response:
 
-```shell
-workos fga warrant create user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 member team:stark
-workos fga warrant create team:stark parent report:7
+```json
+{
+  "authorized": true
+}
 ```
 
-### (B) Using the SDK
+Alice is authorized because her `workspace-admin` role on the Engineering workspace includes `project:edit`, which flows down to all projects in that workspace.
+
+### Check by resource ID
+
+You can also reference resources by their internal WorkOS ID:
+
+```bash
+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": "project:edit",
+    "resource_id": "authz_resource_02HDEF"
+  }'
+```
 
-<LanguageSelector languages={['go', 'java', 'js', 'python']}>
-  Install the SDK using the command below.
+### Integrate into your application
 
-  <CodeBlock title="Install the WorkOS SDK" file="install-sdk">
-    <CodeBlockTab language="js" file="install-sdk-npm" title="npm" />
-    <CodeBlockTab language="js" file="install-sdk-yarn" title="Yarn" />
-    <CodeBlockTab language="java" file="install-sdk-maven" title="Maven" />
-    <CodeBlockTab language="java" file="install-sdk-gradle" title="Gradle" />
-  </CodeBlock>
-</LanguageSelector>
+Here's how an access check looks in practice, protecting an API endpoint:
 
-Create warrants programmatically from your application using the SDK.
+```javascript
+import { WorkOS } from '@workos-inc/node';
 
-<CodeBlock title="Create Warrants" file="create-warrants" />
+const workos = new WorkOS(process.env.WORKOS_API_KEY);
+
+app.patch('/projects/:projectId', async (req, res) => {
+  const { organizationMembershipId } = req.user;
+  const { projectId } = req.params;
+
+  const { authorized } = await workos.authorization.check({
+    organizationMembershipId,
+    permissionSlug: 'project:edit',
+    resourceExternalId: projectId,
+    resourceTypeSlug: 'project',
+  });
+
+  if (!authorized) {
+    return res.status(403).json({ error: 'Forbidden' });
+  }
+
+  const project = await updateProject(projectId, req.body);
+  return res.json(project);
+});
+```
+
+Access checks are designed to be low-latency and reflect role changes immediately—without requiring cache invalidation or waiting for propagation delays.
 
 ---
 
-## (4) Check and query access
+## 6. Discover access
 
-Now that we have our resource types and some warrants set up, we can check and query access.
+FGA provides discovery endpoints that power common product features like filtered navigation, member lists, and sharing dialogs.
 
-Since we assigned `[team:stark]` as the `parent` team of `[report:7]` and `[user:d6ed6474-784e-407e-a1ea-42a91d4c52b9]` as a `member` of `[team:stark]`, they should automatically be a `viewer` of `[report:7]`. Let's do a check to make sure.
+### List resources a user can access
 
-### (A) Using the CLI
+Find all projects Alice (`om_01HXYZ`) can edit within the Engineering workspace:
 
-Check if a subject has a given relation on a resource.
+```bash
+curl "https://api.workos.com/authorization/organization_memberships/om_01HXYZ/resources?permission_slug=project:edit&parent_resource_type_slug=workspace&parent_resource_external_id=workspace_01H" \
+  -H "Authorization: Bearer sk_example_123456789"
+```
 
-```shell title="Check if user is viewer of report:7"
-workos fga check user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 viewer report:7
+This powers features like a sidebar that shows only the projects a user has access to, or a project picker filtered to resources the user can modify.
+
+### List users with access to a resource
+
+Find all users who can edit a specific project:
+
+```bash
+curl "https://api.workos.com/authorization/resources/authz_resource_02HDEF/organization_memberships?permission_slug=project:edit" \
+  -H "Authorization: Bearer sk_example_123456789"
 ```
 
-Query which resources a user has a given relation on.
+By default, this returns users with direct role assignments on the resource. To include users with inherited access (from workspace or organization roles), use the `assignment` parameter:
 
-```shell title="List reports where user is a viewer"
-workos fga query 'select report where user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 is viewer'
+```bash
+# All users who can edit this project (direct + inherited)
+curl "https://api.workos.com/authorization/resources/authz_resource_02HDEF/organization_memberships?permission_slug=project:edit&assignment=indirect" \
+  -H "Authorization: Bearer sk_example_123456789"
 ```
 
-### (B) Using the SDK
+This powers sharing dialogs, member lists, and compliance audits.
 
-Check if a subject has a given relation on a resource.
+---
+
+## Putting it all together
 
-<CodeBlock title="Check if user is viewer of report:7" file="check" />
+Here's the complete flow for our project management app:
 
-Query which resources a user has a given relation on.
+```text
+1. Resource type hierarchy → Define workspace and project resource types in the Dashboard
+2. Privileges → Create roles (workspace-admin, project-editor) with scoped permissions
+3. Resources  → Register workspaces and projects via API as users create them
+4. Access     → Assign roles to users on specific resources
+5. Enforce    → Check permissions before allowing actions
+6. Discover   → Query which resources a user can access for navigation and UI
+```
 
-<CodeBlock title="List reports where user is viewer" file="query" />
+The hierarchy does the heavy lifting. A single `workspace-admin` assignment grants access to every project in that workspace. When new projects are created, the admin automatically has access—no additional assignments needed.
 
 ---
 
-## Summary
+## Next steps
 
-That's it! We've now setup a powerful authorization system for our application that features a hierarchy of privileges (owner → editor → viewer) and inheritance of privileges based on team membership.
+- [Resource Types](/fga/resource-types) – Design your hierarchy for different product patterns
+- [Roles and Permissions](/fga/roles-and-permissions) – Understand permission inheritance in depth
+- [Resources](/fga/resources) – Learn about external IDs, sync strategies, and modeling guidance
+- [Access Checks](/fga/access-checks) – JWT vs. API checks and integration patterns
+- [AuthKit Integration](/fga/authkit-integration) – Embed permissions in access tokens

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

@@ -0,0 +1,78 @@
+---
+title: Resource Discovery
+description: 'Find which resources a user can access, or who has access to a resource.'
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/resource-discovery.mdx
+---
+
+## Overview
+
+Beyond permission checks, FGA provides endpoints to discover access relationships. These power common product features like member lists, a sharing dialog, and scoped navigation.
+
+---
+
+## List users for a resource
+
+Find all users with access to a resource:
+
+```bash
+curl "https://api.workos.com/authorization/resources/authz_resource_01HXYZ/organization_memberships?permission_slug=project:edit" \
+  -H "Authorization: Bearer sk_example_123456789"
+```
+
+### Direct vs. indirect assignments
+
+Use the `assignment` parameter to control whether results include only users with direct assignments or also those with inherited access:
+
+```bash
+# Only users with a direct role assignment on this resource
+curl "https://api.workos.com/authorization/resources/resource_01HXYZ/organization_memberships?permission_slug=project:edit&assignment=direct" \
+  -H "Authorization: Bearer sk_example_123456789"
+
+# All users who can access this resource (direct + inherited)
+curl "https://api.workos.com/authorization/resources/resource_01HXYZ/organization_memberships?permission_slug=project:edit&assignment=indirect" \
+  -H "Authorization: Bearer sk_example_123456789"
+```
+
+**Direct assignments** (default) return only users with an explicit role on this specific resource. For example, users assigned as `project-editor` directly on this project.
+
+**Indirect assignments** return all users with access, including through parent resources. Users with `workspace-admin` on the parent workspace appear in results, as do users with organization-level roles that grant the permission.
+
+### Real-world examples
+
+**Access audit** – An admin reviews who has been explicitly granted access to a sensitive project. Use `assignment=direct` to see only users with direct role assignments, excluding those with inherited access from workspace or org roles.
+
+**Member list** – A project page displays all team members who can access the project. Use `assignment=indirect` to show everyone who can access it, whether through direct project membership, workspace membership, or organization-level roles.
+
+**Sharing confirmation** – Before inviting a collaborator to a project, verify who already has access. Query with `permission=project:view&assignment=indirect` to see all users who can view the project, including inherited access.
+
+**Compliance reporting** – Generate reports of users with admin access to critical resources. Use `permission_slug=workspace:admin&assignment=direct` to identify users explicitly assigned admin roles, separate from those with inherited organization-level admin access.
+
+---
+
+## List resources for a user
+
+Find all resources where a user has a specific permission:
+
+```bash
+curl "https://api.workos.com/authorization/organization_memberships/om_01HXYZ/resources?permission_slug=project:edit&parent_resource_id=authz_resource_01HXYZ" \
+  -H "Authorization: Bearer sk_example_123456789"
+```
+
+This endpoint returns all child resources of a parent where the user has the specified permission, including through inheritance. For example, if a user's `workspace-admin` role includes `proj:edit`, all projects in that workspace appear when querying for `proj:edit`—even without direct project assignments.
+
+### Real-world examples
+
+**Scoped navigation** – A project management app shows only the projects a user can access in their sidebar within a specific workspace. Query with `parent_resource_id` set to the workspace.
+
+**Sharing dialog** – When inviting a collaborator, filter the project picker to show only projects where the user has edit access within the current workspace.
+
+**"My Projects" view** – Display all projects under a workspace where a user can perform specific actions. The query includes projects accessible through higher-level roles.
+
+---
+
+## How inheritance affects results
+
+When listing users for a resource, the full permission hierarchy is considered. A user with `workspace-admin` on a workspace will appear in results for all projects in that workspace, even without direct project assignments. Use the `assignment` parameter to control whether inherited access is included.
+
+When listing resources for a user, only resources where the user has a direct role assignment on the parent resource or any child resources are returned. Indirect assignment lookups are not supported yet.