@workos/mcp-docs-server 0.1.0

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

@@ -0,0 +1,174 @@
+---
+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.
+originalPath: .tmp-workos-clone/packages/docs/content/fga/quick-start.mdx
+---
+
+## Before getting started
+
+To get the most out of this guide, you should 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)
+
+## What you'll build
+
+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. 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.
+
+## API resource definitions
+
+[Schema](/fga/schema)
+: A schema defining the different types of relationships available on your application's resources and how those relationships can be inherited
+
+[Warrant](/fga/warrants)
+: A rule assigning a relationship between two resources in your application
+
+## (1) Install the WorkOS CLI
+
+Install the WorkOS CLI using [Homebrew](https://brew.sh/).
+
+```shell
+brew install workos/tap/workos-cli
+```
+
+To initialize the CLI, use the command below. Follow the prompts to complete setup.
+
+```shell
+workos init
+```
+
+---
+
+## (2) Define a resource type schema
+
+Our application has three types of resources: reports, teams, and users. Our authorization model should meet the following requirements:
+
+- 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.
+
+We'll define the following resource type schema to fulfill these requirements:
+
+```fga title="schema.txt"
+version 0.3
+
+type user
+
+type team
+  relation member [user]
+
+type report
+  relation parent [team]
+  relation owner [user]
+  relation editor [user]
+  relation viewer [user]
+
+  inherit editor if
+    relation owner
+
+  inherit viewer if
+    any_of
+      relation editor
+      relation member on parent [team]
+
+```
+
+### (A) Using the CLI
+
+Create a file called `schema.txt` containing the schema definition from above. Then use the CLI to update your schema in WorkOS FGA.
+
+```shell
+workos fga schema apply schema.txt
+```
+
+### (B) Using the FGA Dashboard
+
+Define a resource type schema from the FGA dashboard using the schema editor available on the [Schema](https://fga.workos.com/schema) page.
+
+---
+
+## (3) Create warrants
+
+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.
+
+For example, let's create two warrants:
+
+- 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]`
+
+### (A) Using the CLI
+
+Create warrants using the CLI.
+
+```shell
+workos fga warrant create user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 member team:stark
+workos fga warrant create team:stark parent report:7
+```
+
+### (B) Using the SDK
+
+<LanguageSelector languages={['go', 'java', 'js', 'python']}>
+  Install the SDK using the command below.
+
+  <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>
+
+Create warrants programmatically from your application using the SDK.
+
+<CodeBlock title="Create Warrants" file="create-warrants" />
+
+---
+
+## (4) Check and query access
+
+Now that we have our resource types and some warrants set up, we can check and query access.
+
+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.
+
+### (A) Using the CLI
+
+Check if a subject has a given relation on a resource.
+
+```shell title="Check if user is viewer of report:7"
+workos fga check user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 viewer report:7
+```
+
+Query which resources a user has a given relation on.
+
+```shell title="List reports where user is a viewer"
+workos fga query 'select report where user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 is viewer'
+```
+
+### (B) Using the SDK
+
+Check if a subject has a given relation on a resource.
+
+<CodeBlock title="Check if user is viewer of report:7" file="check" />
+
+Query which resources a user has a given relation on.
+
+<CodeBlock title="List reports where user is viewer" file="query" />
+
+---
+
+## Summary
+
+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.

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

@@ -0,0 +1,92 @@
+---
+title: Resources
+description: >-
+  Resources are FGA's references to your application's access controlled
+  resources.
+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_.
+
+## Overview
+
+```shell
+      report    :    balance-sheet
+        |                  |
+   Resource Type      Resource ID
+```
+
+Resources consist of three attributes:
+
+- **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).
+
+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.
+
+## 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.
+
+For example, given the following warrant:
+
+```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"
+  }
+}
+```
+
+FGA will automatically create two resources upon creation of the warrant:
+
+```json title="report:balance-sheet"
+{
+  "resource_type": "report",
+  "resource_id": "balance-sheet"
+}
+```
+
+```json title="user:john-doe"
+{
+  "resource_type": "user",
+  "resource_id": "john-doe"
+}
+```
+
+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.
+
+> 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.
+
+## Metadata
+
+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.
+
+```json title="user:john-doe w/ metadata"
+{
+  "resource_type": "user",
+  "resource_id": "john-doe",
+  "meta": {
+    "email": "john-doe@acme-corp.com",
+    "isActivated": true
+  }
+}
+```
+
+```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."
+  }
+}
+```
+
+> There is a 50kb limit on the size of the metadata object.

package/.docs/organized/docs/fga/schema-management.mdx

@@ -0,0 +1,224 @@
+---
+title: Schema Management
+description: >-
+  Learn how to test, debug, and safely apply changes to your authorization
+  schema and setup a GitOps workflow to automatically validate and apply changes
+  to production.
+originalPath: .tmp-workos-clone/packages/docs/content/fga/schema-management.mdx
+---
+
+## Overview
+
+Designing a schema that meets your requirements and using it in production for the first time is only the beginning of your fine-grained authorization journey. As your product's authorization requirements change, you will need to evolve your schema to meet those requirements.
+
+To do this safely, you need a process in place to test, debug, and safely apply changes to your schema in production. In case of bugs, you also need the ability to roll back to a previous (working) schema if needed.
+
+This guide will explain how to use the [FGA Dashboard](https://fga.workos.com) and [WorkOS CLI](https://github.com/workos/workos-cli) to test and debug your schema. We will use the CLI and the [CLI GitHub Action](https://github.com/workos/cli-action) to setup a GitOps workflow that automatically tests and applies changes to your schema as part of your software development life cycle (SDLC).
+
+## Before getting started
+
+To get the most out of this guide, you'll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+- Your WorkOS [API Key](/glossary/api-key)
+- The [WorkOS CLI](/fga/quick-start/1-install-the-workos-cli)
+
+---
+
+## Test Your Schema
+
+Let's create a shell script that uses the WorkOS CLI to test the example schema below.
+
+> Note: we've decided to prefix permissions in our authorization model with `can_` (`can_invite_users`) to imply an action. This is not a required convention, so feel free to use relation names that suit your application.
+
+```fga title="schema.txt"
+version 0.3
+
+type user
+
+type organization
+    relation role_admin [user]
+    relation role_member [user]
+    relation can_invite_users []
+    relation can_remove_users []
+    relation can_view_users []
+
+    inherit role_member if
+        relation role_admin
+
+    inherit can_invite_users if
+        relation role_admin
+
+    inherit can_remove_users if
+        relation role_admin
+
+    inherit can_view_users if
+        relation role_member
+
+```
+
+First, apply the schema
+
+```shell title="Apply the example schema"
+workos fga schema apply schema.txt
+```
+
+Next, use the `fga warrant create` command to setup some warrants.
+
+```shell title="Setup test data"
+workos fga warrant create user:acme_admin role_admin organization:org_acme
+workos fga warrant create user:acme_member role_member organization:org_acme
+```
+
+Then use the `fga check` command with the `--assert` flag to assert that a permission check returns the expected result.
+
+```shell title="Make assertions"
+workos fga check user:acme_admin can_invite_users organization:org_acme --assert true
+workos fga check user:acme_admin can_remove_users organization:org_acme --assert true
+workos fga check user:acme_admin can_view_users organization:org_acme --assert true
+
+workos fga check user:acme_member can_invite_users organization:org_acme --assert false
+workos fga check user:acme_member can_remove_users organization:org_acme --assert false
+workos fga check user:acme_member can_view_users organization:org_acme --assert true
+```
+
+Finally, use the `fga resource delete` command to clean up the test data. This makes it easy to re-run tests with a clean environment in the future.
+
+```shell title="Clean up test data"
+workos fga resource delete user:acme_admin
+workos fga resource delete user:acme_member
+workos fga resource delete organization:org_acme
+```
+
+---
+
+## Debug Your Schema
+
+The simplest way to understand (debug) why your schema is (or is not) answering a permission check as you expect it to is via the [Check page](https://fga.workos.com/check) or using the `--debug` flag via the CLI.
+
+### Using the FGA Dashboard
+
+To debug a permission check from the FGA dashboard, navigate to the [Check page](https://fga.workos.com/check). Enter valid arguments for the permission check you want to debug and click `Check Access`. The page will display the result of the permission check and a tree visualizing all of the paths in the authorization graph that were explored to reach the result.
+
+### Using the CLI
+
+To debug a permission check using the CLI, use the `fga check` command with the `--debug` flag:
+
+```shell title="Debug a permission check"
+workos fga check user:james can_approve_purchase purchase:pur_123 --debug
+```
+
+Permission checks that use the `--debug` flag will output the check result and a tree visualizing all of the paths in the authorization graph that were explored to reach the result.
+
+> Note: running the `fga check` command with the `--debug` flag will execute the check without any caching enabled.
+
+#### Tests
+
+The CLI provides a streamlined way to run multiple tests against your schema using a single `workos fga test command`. The `test` command will set up warrants, perform checks, and handle teardown.
+
+It also supports running multiple test files from a directory, allowing you to organize tests in a structure that fits your application.
+
+```yaml title="org-roles.test.yaml"
+setup:
+  warrants:
+    - subject: user:acme_admin
+      relation: role_admin
+      resource: organization:org_acme
+    - subject: user:acme_member
+      relation: role_member
+      resource: organization:org_acme
+
+tests:
+  - name: acme_admin can invite users
+    check:
+      subject: user:acme_admin
+      relation: can_invite_users
+      resource: organization:org_acme
+    expect: true
+
+  - name: acme_admin can remove users
+    check:
+      subject: user:acme_admin
+      relation: can_remove_users
+      resource: organization:org_acme
+    expect: true
+
+  - name: acme_admin can view users
+    check:
+      subject: user:acme_admin
+      relation: can_view_users
+      resource: organization:org_acme
+    expect: true
+
+  - name: acme_member cannot invite users
+    check:
+      subject: user:acme_member
+      relation: can_invite_users
+      resource: organization:org_acme
+    expect: false
+
+  - name: acme_member cannot remove users
+    check:
+      subject: user:acme_member
+      relation: can_remove_users
+      resource: organization:org_acme
+    expect: false
+
+  - name: acme_member can view users
+    check:
+      subject: user:acme_member
+      relation: can_view_users
+      resource: organization:org_acme
+    expect: true
+
+teardown:
+  resources:
+    - user:acme_admin
+    - user:acme_member
+    - organization:org_acme
+```
+
+To run the tests defined in the `schema.test.yaml` file, use the following command:
+
+```shell title="Run tests"
+workos fga test org-roles.test.yaml
+```
+
+> The teardown section is optional and used for cleaning up specific data (resources or warrants). If you want to automatically cleanup **all resources and warrants** created during the test, you can also use the `--cleanup` flag when running the `workos fga test` command.
+
+---
+
+## GitOps Workflow
+
+Now that we have a script to test that our schema works as we expect, let's setup a GitHub Action to automatically test changes to the schema and apply the schema if all of the tests pass.
+
+```yaml title=".github/workflows/fga.yaml"
+name: Test FGA Schema
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install WorkOS CLI
+        uses: workos/cli-action@v1
+        with:
+          version: latest
+      - name: Test Schema
+        run: |
+          workos fga schema apply schema.txt
+          workos fga test tests/org-roles.test.yaml
+        env:
+          WORKOS_ACTIVE_ENVIRONMENT: staging
+          WORKOS_ENVIRONMENTS_HEADLESS_API_KEY: <your_workos_staging_api_key>
+      - name: Apply Schema to Production
+        if: github.ref == 'main' && github.event_name == 'push'
+        run: |
+          workos fga schema apply schema.txt
+        env:
+          WORKOS_ACTIVE_ENVIRONMENT: production
+          WORKOS_ENVIRONMENTS_HEADLESS_API_KEY: <your_workos_production_api_key>
+```