@workos/mcp-docs-server 0.1.0

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

@@ -0,0 +1,388 @@
+---
+title: Schema
+description: >-
+  Define authorization logic independently from application code using a
+  domain-specific language (DSL).
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/schema.mdx
+---
+
+## Overview
+
+A schema is the core structure of an authorization model in FGA. It defines the types of resources, the relations between them, and the policies that govern access.
+
+A schema can be represented in two formats:
+
+- **JSON** – Accepted by [Schema API](/reference/fga/schema) endpoints when using `Content-Type: application/json`.
+- **FGA Schema Language** – A more developer-friendly domain-specific language (DSL) that is applied via the `apply` command with the CLI or on the [FGA Dashboard](https://fga.workos.com/schema).
+
+Schemas allow you to manage authorization logic independently from application logic. They can be versioned, stored in Git, and applied via the CLI:
+
+```shell
+workos fga schema apply ./schema.txt
+```
+
+Once applied, changes take effect immediately, meaning any updates to authorization logic will instantly reflect in subsequent permission checks and queries.
+
+FGA Schema Language transpiles into JSON format so that you can write your authorization model in a more readable and maintainable way, but still use JSON for API calls if you prefer.
+
+## JSON vs Schema Language
+
+The JSON representation of a schema is the raw format that FGA uses to define resource types, relations, and inheritance rules. However, it can be verbose and difficult to read - especially for complex authorization models.
+
+Consider the following examples:
+
+### JSON Representation
+
+```json
+{
+  "resource_types": [
+    {
+      "type": "user",
+      "relations": {
+        "manager": {
+          "allowed_types": ["user"]
+        }
+      }
+    },
+    {
+      "type": "store",
+      "relations": {
+        "owner": {
+          "allowed_types": ["user"]
+        },
+        "editor": {
+          "allowed_types": ["user"],
+          "inherit_if": "owner"
+        },
+        "viewer": {
+          "allowed_types": ["user"],
+          "inherit_if": "editor"
+        }
+      }
+    },
+    {
+      "type": "item",
+      "relations": {
+        "owner": {
+          "allowed_types": ["user"]
+          "inherit_if": "owner",
+          "of_type": "store",
+          "with_relation": "parent"
+        },
+        "editor": {
+          "allowed_types": ["user"],
+          "inherit_if": "any_of",
+          "rules": [
+            {
+              "inherit_if": "owner"
+            },
+            {
+              "inherit_if": "editor",
+              "of_type": "store",
+              "with_relation": "parent"
+            },
+            {
+              "inherit_if": "manager",
+              "of_type": "user",
+              "with_relation": "owner"
+            }
+          ]
+        },
+        "viewer": {
+          "allowed_types": ["user"],
+          "inherit_if": "editor"
+        },
+        "parent": {
+          "allowed_types": ["store"]
+        }
+      }
+    }
+  ]
+}
+```
+
+### Schema Language Representation
+
+```fga
+version 0.3
+
+type user
+    relation manager [user]
+
+type store
+    relation owner [user]
+
+    relation viewer [user]
+    inherit viewer if
+        relation editor // editors are also viewers
+
+    relation editor [user]
+    inherit editor if
+        relation owner
+
+type item
+    // An item can have a parent store
+    relation parent [store]
+
+    relation owner [user]
+    inherit owner if
+        relation owner on parent [store]
+
+    relation editor [user]
+    inherit editor if
+        any_of
+            relation owner
+            relation editor on parent [store]
+            relation manager on owner [user]
+
+    relation viewer [user]
+    inherit viewer if
+        relation editor
+```
+
+The FGA schema language representation is more concise, easier to read, and supports comments. These features make it simpler to define and manage complex authorization models in a more developer-friendly format.
+
+## Schema Syntax
+
+### Version
+
+Each schema must start with a `version` declaration. This version declaration dictates the version of the schema language the transpiler will use to convert the schema into its JSON representation. As we add support for new features and functionality to the schema language, we will release new versions of it. Versioning the language in this way allows us to ensure backwards compatibility as we roll out these enhancements. See a full changelog of schema versions [here](/fga/schema/schema-changelog).
+
+<CodeBlock file="schema-version" />
+
+### Comments
+
+Comments are prefixed with `//`. Comments are ignored by the transpiler.
+
+<CodeBlock file="schema-comment" />
+
+### Resource Types
+
+Resource types are the basic building blocks of an authorization model in FGA. Each resource type defines a set of relationships that can exist on a specific type of resource (e.g. store, item, etc). These relationships can be assigned to other resources (e.g. user) known as subjects.
+
+Resource types are an incredibly flexible way to define authorization models, allowing you to express complex hierarchical and inherited relationships. They can be created directly in the [FGA dashboard](https://fga.workos.com/schema), via the [Resource Types API](/reference/fga/resource-type/create) or by applying the schema with the CLI.
+
+Let's explore the various attributes of resource types by creating a schema-based authorization model for a simple e-commerce application that has three resource types: users, stores, and items.
+
+First, define a resource type using the `type` keyword. Each resource type must have a unique string as its type. Let's start defining the resource types for our e-commerce application:
+
+<CodeBlock file="schema-resource-types" />
+
+### Relations
+
+With the basic definitions above, we've started building an authorization model for our application that will allow us to create fine grained access control rules for stores, items, and users, helping us answer questions like:
+
+```shell
+Does [user:1] have the ability to [edit] [item:x]?
+is [user:1] the [owner] of [store:3]?
+```
+
+In order to create access rules using our resource types, we first need to define the relationships available on a resource of that type. For example, if we want to specify that `[user:A] is an [owner] of [store:S]`, we must add an `owner` relation to the `store` resource type.
+
+By default, a subject can only have a relation on a resource explicitly. This means the relation must be _explicitly_ granted via a [warrant](/fga/warrants).
+
+Let's add some relations to our resource types.
+
+In our application, a store can have `owners`, `editors`, and `viewers`. `owners` and `editors` have more privileged access (like being able to modify details about a store) than `viewers` (who have read-only access).
+
+An item can have the same three relations as a store _plus_ a fourth relation called `parent`. This is because a store can be the `parent` of an item, meaning the item belongs to that store. We'll use this relation later to implement inherited relations on items.
+
+Lastly, our `user` resource type is relatively simple and has one relation: `manager`. This is because a user can be the `manager` of another user. We'll use this relation later to enable inherited relations based on user hierarchies.
+
+Let's add these relations to our resource types:
+
+<CodeBlock file="schema-relations" />
+
+With these resource types, we can now create authorization rules that specify exactly which users are `owners`, `editors`, and `viewers` of each store or item. We can also assign stores as `parents` of items, and users as `managers` of other users.
+
+Use brackets [] in the schema language after defining a relation to enforce which type(s) of subjects can be assigned the relation.
+
+Use empty type restrictions to define computed relationships with no direct subjects. This is useful for defining a relation that cannot be assigned directly to a subject but is used to make an authorization check from your application.
+
+> Version `0.1` of the schema language does not support type safety on relations.
+
+### Inheritance Rules
+
+While only using explicitly assigned relations to build your authorization model can be powerful, creating warrants for each and every relationship in an application can become tedious or infeasible for larger, more complex use cases. That's why relations can define rules under which they can be inherited (e.g. `a user is an editor of a store if they're an owner of that store`).
+
+There are two ways in which relations can be inherited:
+
+- Relation Inheritance
+- Resource Inheritance
+
+#### Relation Inheritance
+
+In practice, it's common for relations to have overlap (e.g. an `owner` has the same privileges as an `editor` + additional privileges). For example, in many applications a user with write privileges inherits read privileges too.
+
+In our example application, an `owner` will inherit both the `editor` and the `viewer` relations, and an `editor` will inherit the `viewer` relation. Instead of having to explicitly assign each of the `owner`, `editor`, and `viewer` relations to a user who is an `owner`, resource types allow you to specify an inheritance hierarchy (e.g. the `editor` relation is inherited if the user is an `owner`) using the `inherit_if` property.
+
+Let's add `inherit <relation> if` rules to our `store` and `item` resource types specifying that:
+
+- `owners` are also `editors`
+- `editors` are also `viewers`
+
+<CodeBlock file="schema-relation-inheritance" />
+
+With our `inherit <relation> if` rules in place, we can simply grant a user the `editor` relation and they will implicitly inherit the `viewer` relation. `inherit` rules also work recursively on other inherited relations, so assigning a user the `owner` relation will implicitly grant that user _both_ the `editor` and `viewer` relations. This is because `owner` will inherit `editor` and `editor` will in turn inherit `viewer`.
+
+This will simplify our access checks and cut down on the number of warrants we need to create for each user.
+
+#### Resource Inheritance
+
+In many applications, resources themselves have a hierarchy (e.g. a document belongs to a folder, a user belongs to a team, a team belongs to an organization, etc.) and the access rules for these resources follow that hierarchy (e.g. the owner of a folder is the owner of any document in that folder).
+
+Using the following two rules:
+
+```txt
+inherit <relation> if
+```
+
+```txt
+relation <resource_type.relation> on <relation> [<resource_type>]
+```
+
+We can specify that a relation can be inherited when a user has a particular relation (`<resource_type.relation>`) on another resource (`<resource_type>`) that has a particular relation (`<relation>`) on the resource we are checking access to.
+
+For example, a user is an `editor` of a document if they are an `editor` of a `folder` that is the document's `parent`. In our example app, let's define the following three resource inheritance rules:
+
+1. A user is an `owner` of an item if that user is an `owner` of a `store` that is the item's `parent`.
+2. A user is an `editor` of an item if that user is an `editor` of a `store` that is the item's `parent`.
+3. A user is an `editor` of an item if that user is the `manager` of the `user` that is the item's `owner`.
+
+> **NOTE:** Some of the relations below will be [composing multiple inheritance rules together using logical operators](/fga/schema/schema-syntax/logical-operators). We'll cover this in detail later.
+
+<CodeBlock file="schema-resource-inheritance" />
+
+These rules make it easy to define inheritance rules for complex relationships between resources so we don't have to create a large number of explicit warrants. Without them, we'd need to create a warrant for every item &harr; store &harr; user relationship in our application. This could easily be thousands, if not hundreds of thousands of rules.
+
+### Logical Operators
+
+With both the two types of relation inheritance rules in our toolkit, we can create authorization models for a majority of use cases, but there are still some scenarios that require a combination of these inheritance rules (e.g. a user is an `editor` of an item if they are an `owner` of that item **OR** they are the `manager` of another user who is an `editor` of that item).
+
+To design authorization models that cover such scenarios, relations can compose multiple inheritance rules using _logical operators_ to form more complex conditions.
+
+The three supported logical operations are `any_of`, `all_of`, and `none_of`.
+
+#### any_of
+
+The `any_of` operation allows you to specify that a relation be inherited if _at least one of_ the rules in the set is satisfied. In other words, it works like the logical _OR_ operation.
+
+The following resource type specifies an `editor-or-viewer` relation that is inherited if the user is an `editor` **OR** if the user is a `viewer`:
+
+<CodeBlock file="schema-any-of" />
+
+#### all_of
+
+The `all_of` rule type allows you to specify that a relation be inherited if _all of_ the rules in the set are satisfied. In other words, it works like the logical _AND_ operation.
+
+The following resource type specifies an `editor-and-viewer` relation that is implicitly granted if the user is an `editor` **AND** the user is a `viewer`:
+
+<CodeBlock file="schema-all-of" />
+
+#### none_of
+
+The `none_of` rule type allows you to specify that a relation be inherited if _none of_ the rules in the set are satisfied. In other words, it works like the logical _NOR_ operation.
+
+The following resource type specifies a `not-editor-and-not-viewer` relation that is implicitly granted if the user is _not_ an `editor` **AND** the user is _not_ a `viewer`:
+
+<CodeBlock file="schema-none-of" />
+
+### Policies
+
+Policies are a way to define custom logic that can be used in your schema. They allow you to create complex rules that go beyond simple relation inheritance. Policies can be defined using the `policy` keyword and can include parameters, expressions, and logical conditions.
+
+<CodeBlock file="schema-policies" />
+
+Read more about policies in the [Policies documentation](/fga/policies).
+
+### Group Warrants
+
+Define type restrictions on [group warrants](/fga/warrants/group-warrants) by joining the type and expected relation with a `#`. For example, `relation editor [group#member]` means that the `editor` relation can be assigned to warrants where `group` is the subject type and `member` is the subject relation.
+
+Group warrants are a special type of warrant that allow you to define exceptions to schema relationships at runtime. See the [Group Warrant documentation](/fga/warrants/group-warrants) for more details.
+
+<CodeBlock file="schema-group-warrants" />
+
+If your relation type defines a resource type and no group warrant types, it will default to allow all group warrants.
+
+For example:
+
+```js
+// Allows subject_type == "group" and subject_relation == null | <any_value>
+relation editor [group]
+
+// Allows subject_type == "group" and subject_relation == "member"
+relation editor [group#member]
+
+// Allows subject_type == "group" and subject_relation == "member" | "owner"
+relation editor [group#member, group#ownwer]
+
+// Allows subject_type == "group" and subject_relation == null | "member"
+relation editor [group, group#member]
+```
+
+## Converting Schema Language to JSON
+
+You can convert the FGA schema language to JSON using the `workos fga schema convert` command. This command transpiles the schema language into its JSON representation, which can then be used with the FGA API.
+
+```shell
+workos fga schema convert schema.txt --to json --output raw > schema.json
+```
+
+## Schema Changelog
+
+### v0.3
+
+- Add support for policy in the schema
+
+```fga
+version 0.3
+
+type user
+
+type group
+    relation member [user]
+
+type asset
+    relation access_diagnostics []
+    relation service_manager [group]
+
+    inherit access_diagnostics if
+        all_of
+          relation member on service_manager [group]
+          policy is_in_geo_fence
+
+policy is_in_geo_fence(user_location map, geofence map) {
+    user_location.lat >= geofence.min_lat &&
+    user_location.lat <= geofence.max_lat &&
+    user_location.lon >= geofence.min_lon &&
+    user_location.lon <= geofence.max_lon
+}
+
+```
+
+### v0.2
+
+- Add support for resource-type relation type safety
+- Add support for group warrant types
+
+```fga
+version 0.2
+
+type report
+    relation parent [organization, organization#member]
+    relation owner [user]
+    relation editor [user]
+```
+
+### v0.1
+
+- Initial implementation of the schema language
+- Supported features:
+  - Transpiler version
+  - Resource types
+  - Relations
+  - Inheritance rules
+  - Resource inheritance
+  - Logical operators

package/.docs/organized/docs/fga/warrant-tokens.mdx

@@ -0,0 +1,44 @@
+---
+title: Warrant Tokens
+description: >-
+  Configure whether you favor performance or consistency on a per request basis
+  depending on your application's consistency requirements.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/warrant-tokens.mdx
+---
+
+## Overview
+
+FGA is a distributed service deployed to multiple cloud regions. All traffic to the FGA API flows through a single endpoint (`api.workos.com/fga`). To ensure reliability, data is replicated to multiple regions behind the scenes. To maximize performance, FGA is an _eventually consistent_ service by default.
+
+In order to balance performance and consistency, FGA supports a _bounded staleness protocol_ similar to Google Zanzibar's _Zookie_ protocol. This allows client applications to specify when they prefer the fastest results (to minimize latency added by authorization checks) and when they prefer immediately consistent results (to ensure recent changes to permissions are reflected for a particular check or query).
+
+FGA generates an opaque token (known as a _Warrant Token_) for all warrant _write_ operations (i.e. creating or deleting warrants). Each Warrant Token uniquely identifies a warrant write operation. All warrant write operations return a Warrant Token in the response body.
+
+```shell
+{
+  "warrant_token": "MjM0fDM0MzQyM3wyMTM0MzM0MzY0NQ=="
+}
+```
+
+## `Warrant-Token` Header
+
+Unlike traditional eventually-consistent distributed systems, FGA allows clients to specify their desired consistency level via Warrant Tokens. Clients can pass a previously generated Warrant Token via the `Warrant-Token` header on check, query, and list warrants requests to instruct the server to process the request using data _no older_ than the write operation identified by the specified Warrant Token. This allows clients to ensure that a particular check, query, or list warrants request has the data necessary to give the most up-to-date result as dictated by the application's authorization requirements.
+
+### `latest`
+
+In some cases, a client may need an up-to-date result but may not have an accompanying Warrant Token to use for the request. In this scenario, the client can pass the special value `latest` in the `Warrant-Token` header to instruct FGA to use the most up-to-date data:
+
+```shell
+'Warrant-Token: latest'
+```
+
+Note that using the `latest` token effectively instructs FGA to bypass all caches in favor of hitting the database for the most up-to-date result. Therefore, it can incur additional performance overhead, so it's recommended to only use `latest` sparingly. Instead, opt to use server-provided Warrant Tokens or no token at all (the default consistency) to maximize performance in most cases.
+
+## Storing Warrant Tokens
+
+In practice, clients can store Warrant Tokens in their system on a _per-subject_ basis, passing in the stored token to each read request for that subject to achieve optimal performance. For example, if creating a new warrant (e.g. `user:x is an editor of report:y`) generates a Warrant Token with value `45f87sdf=`, the client can store that token their db along for subject `user:x`. Subsequent checks or queries for `user:x` can then include that stored Warrant Token for the optimal balance of performance and consistency.
+
+## Default consistency
+
+Passing a Warrant Token on check, query, and list warrants requests is optional. If a Warrant Token is not provided, FGA uses a default staleness window to fulfill check and query requests. This window is cache-optimized and is the recommended approach for the 90-95% of read requests that can tolerate short periods (on the order of seconds) of inconsistent results.

package/.docs/organized/docs/fga/warrants.mdx

@@ -0,0 +1,92 @@
+---
+title: Warrants
+description: Warrants specify relationships between resources in your application.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/fga/warrants.mdx
+---
+
+**Warrants** are access rules that specify relationships between the resources in your application (e.g. `[store:A] is [parent] of [item:123]`). WorkOS FGA uses the set warrants and resource types for an application to answer access checks and queries. Individual warrants define explicit relations between resources while resource types define rules (policies) by which some relationships can exist implicitly.
+
+## Overview
+
+```shell
+   tenant:stark-industries  #  admin  @  user:tony-stark
+              |                  |              |
+           Resource           Relation       Subject
+```
+
+Each warrant is composed of three core attributes and an optional _policy_ (more on this later):
+
+- **Resource** - This is the resource the warrant specifies a relationship on. The resource is broken down into a `resource_type` and a `resource_id`. The `resource_type` must refer to a valid [resource type](/fga/schema/schema-syntax/resource-types) defined for the application. The `resource_id` must be a unique identifier used by the application to identify the resource.
+- **Relation** - This is the relationship the warrant specifies between the resource and the subject. The relation must be one of the defined [relations](/fga/schema/schema-syntax/relations) on the referenced `resource_type`. It is often used to specify an action the warrant will grant the subject the ability to perform on the resource (e.g. `editor`, `viewer`, etc.).
+- **Subject** - This is the resource being granted the specified relation. Like the resource, the subject is broken down into a `resource_type`, and a `resource_id`, and optionally a `relation` (to specify a group of subjects). A subject's `resource_type` must refer to a valid resource type defined for the application, and its `resource_id` must be a unique identifier used by the application to identify the resource. While the subject will often times be an individual user or resource, the subject can also specify a _group_ of resources (e.g. in [group warrants](#group-warrants)).
+- **Policy** (optional) - The policy specifies an additional boolean expression to be evaluated _at the time of each check/query request_. The provided expression can reference arbitrary variables which can be provided in check or query requests as _context_. Given some context at check/query time, a warrant's policy must evaluate to `true` in order for the warrant to be considered a match for the check/query. If a warrant's resource, relation, and subject attributes do not match the requested check/query **or** the policy expression evaluates to `false`, the warrant will not be matched during evaluation of the check/query. The policy attribute can be used to implement a form of attribute-based access control (ABAC).
+
+Here is an example warrant specifying that the subject `user:ABC` has the relation `editor` on resource `item:123`:
+
+```json
+{
+  "resource_type": "item",
+  "resource_id": "123",
+  "relation": "editor",
+  "subject": {
+    "resource_type": "user",
+    "resource_id": "ABC"
+  }
+}
+```
+
+## Direct Warrants
+
+A direct warrant represents a relationship between a resource and a _specific_ subject. For example, we can define a warrant specifying that `[user:1] is a [member] of [role:admin]`:
+
+```json
+{
+  "resource_type": "role",
+  "resource_id": "admin",
+  "relation": "member",
+  "subject": {
+    "resource_type": "user",
+    "resource_id": "1"
+  }
+}
+```
+
+## Group Warrants
+
+In some cases, we might need to specify a relationship between a resource and a _group_ of subjects (e.g. `[member]s of [role:admin]`, `[manager]s of [tenant:acme]`, etc). Group warrants are warrants that include the optional `relation` attribute on the `subject`. They specify that _all_ resources matching the subject's `resource_type`, `resource_id`, and `relation` will have the specified `relation` on the resource. For example, we can define a group warrant specifying that `[member]s of [role:admin] are [editor]s of [report:1]`:
+
+```json
+{
+  "resource_type": "report",
+  "resource_id": "1",
+  "relation": "editor",
+  "subject": {
+    "resource_type": "role",
+    "resource_id": "admin",
+    "relation": "member"
+  }
+}
+```
+
+It's important to note that resource inheritance rules achieve the same thing as group warrants, but group warrants are a data-first approach. Group warrants are typically used as an exception for certain resources that might have different sets of requirements than the schema. We typically recommend using resource inheritance rules over group warrants because it is easier to manage a single schema than a set of group warrants defined on several different resources.
+
+## Wildcard Warrants
+
+While FGA is designed to model fine-grained authorization, some use-cases call for more coarse-grained access to individual resources. For example, publicly sharing read privileges on a particular document with all users. Scenarios like this can be modeled using wildcard warrants. A wildcard warrant is a warrant that specifies a wildcard (`*`) for the `subject_id` attribute. This means the warrant applies to _all_ subjects of the specified `subject_type`. Note that group warrants cannot specify a wildcard as the `subject_id`. Here is an example of a wildcard warrant that grants _all users_ `viewer` access to `document:doc_123`:
+
+```json
+{
+  "resource_type": "document",
+  "resource_id": "doc_123",
+  "relation": "viewer",
+  "subject": {
+    "resource_type": "user",
+    "resource_id": "*"
+  }
+}
+```
+
+## Creating and Managing Warrants
+
+Warrants can be created directly in the [FGA dashboard](https://fga.workos.com) or programmatically via API. Refer to the [Warrants API Reference](/reference/fga/warrant/list) to learn more about managing Warrants via API.