Quick Start

To get the most out of this guide, you should have:

• A WorkOS account
• Your WorkOS API Key
• A basic understanding of resource types

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.

Schema

A schema defining the different types of relationships available on your application’s resources and how those relationships can be inherited

Warrant

A rule assigning a relationship between two resources in your application

Install the WorkOS CLI using Homebrew.

brew install workos/tap/workos-cli

To initialize the CLI, use the command below. Follow the prompts to complete setup.

workos init

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:

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]

Create a file called schema.txt containing the schema definition from above. Then use the CLI to update your schema in WorkOS FGA.

workos fga schema apply schema.txt

Define a resource type schema from the FGA dashboard using the schema editor available on the Schema page.

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]

Create warrants using the CLI.

workos fga warrant create user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 member team:stark
workos fga warrant create team:stark parent report:7

Create warrants programmatically from your application using the SDK.

curl "https://api.workos.com/fga/v1/warrants" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '[
    {
      "op": "create",
      "resource_type": "team",
      "resource_id": "stark",
      "relation": "member",
      "subject": {
        "resource_type": "user",
        "resource_id": "d6ed6474-784e-407e-a1ea-42a91d4c52b9"
      }
    },
    {
      "op": "create",
      "resource_type": "report",
      "resource_id": "7",
      "relation": "parent",
      "subject": {
        "resource_type": "team",
        "resource_id": "stark"
      }
    }
  ]'

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.

Check if a subject has a given relation on a resource.

workos fga check user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 viewer report:7

Query which resources a user has a given relation on.

workos fga query 'select report where user:d6ed6474-784e-407e-a1ea-42a91d4c52b9 is viewer'

Check if a subject has a given relation on a resource.

curl "https://api.workos.com/fga/v1/check" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
    "checks": [
      {
        "resource_type": "report",
        "resource_id": "7",
        "relation": "viewer",
        "subject": {
          "resource_type": "user",
          "resource_id": "d6ed6474-784e-407e-a1ea-42a91d4c52b9"
        }
      }
    ]
  }'

Query which resources a user has a given relation on.

curl "https://api.workos.com/fga/v1/query?q=select%20report%20where%20user:d6ed6474-784e-407e-a1ea-42a91d4c52b9%20is%20viewer" \
  -X GET \
  -H "Authorization: Bearer sk_example_123456789"

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.