WorkOS Docs Homepage
Fine-Grained Authorization
API referenceDashboardSign In

Org Roles & Permissions

Allow customers to create and assign org-scoped custom roles, mapping them to a static set of permissions available in your application.

Overview

Today’s B2B customers expect strong access controls in the software they buy. Each customer has a unique business structure with specific authorization needs. These needs shape the access each employee should have within the software.

By building customizable, role-based access control into your product, you create a powerful selling point. It gives customers the freedom to map roles to the exact permissions and capabilities they need.

This guide is now available as an example in the FGA Playground, where you can interact with the schema, warrants, and queries in real-time!

Before getting started

To get the most out of this guide, you’ll need:

What you’ll build

In this guide, we will build a fine grained authorization model for a B2B SaaS application with FGA. The application will allow customers to assign their users a per-organization role that grants access to various capabilities (permissions) in the product.

Customers can dynamically create roles and map them to a subset of the available permissions. These mappings will apply only to their customer organization.

This guide will explain how to:

  1. Define an FGA schema to model your application’s authorization requirements
  2. Create warrants that assign relationships between resources in your application
  3. Make access checks to determine if a user has a given privilege or not

API resource definitions

Schema
A schema defines the types of relationships between your application’s resources. It also shows how these relationships can inherit from one another.
Warrant
A rule assigning a relationship between two resources in your application

1. Install the WorkOS SDK

Don't see an SDK you need? Contact us to request an SDK!

2. Define a resource type schema

We’ll start by defining a resource type schema to represent relationships. Relationships dictate authorization between various resources in our application.

Our product requirements:

  • Every organization has four static permissions: can_read_company_info, can_write_company_info, can_read_reports, and can_write_reports
  • Both read permissions are automatically inherited if a user has the corresponding write permission
  • Each role grants one or more of the available organization permissions on a specific organization (e.g. role:acme_admin grants write_reports on organization:acme)
  • Each user is assigned a role (e.g. role:acme_admin)

To summarize, these are the questions our authorization model should be able to answer:

  • Which permissions does user U have on organization O?
  • Which users have permission P on organization O?
  • Does user U have permission P on organization O?

To model our authorization requirements, let’s define the following schema:

schema.txt

A. Using the CLI

Create a file called schema.txt containing the schema definition from above. Then use the CLI to apply this schema to your WorkOS FGA environment.

B. Using the FGA Dashboard

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

3. Create roles and assign warrants

With our resource type schema defined, we need to assign warrants associating:

  • roles to organization permissions
  • users to organizations
  • users to roles

A. Associate a role with organization permissions

Let’s start by creating warrants. Warrants will associate a role with each of the organization permissions. We will then assign these roles to our users.

Our customers will be able to create custom roles and assign each role a set of permissions for their organization. To keep each role unique across all organizations, we’ll prefix each role’s identifier with its organization’s ID. This approach ensures that roles don’t overlap and makes permission checks straightforward.

Assign organization permissions to a role

B. Associate a user with a role

Now that we’ve associated a role with a set of organization permissions, let’s assign the role to a user. In the context of an application, this is typically done during the signup flow. It can also be part of an admin workflow where an admin user can update their team members’ role assignments.

Assign a role to a user

4. Check and query access

Now that our access model and warrants are set up, we can add access checks in our app that will help us enforce our multi-tenant setup. For example, we might want to check if a particular user (user1) has the ability to edit a report (reportA). The answer to this query will depend on multiple factors including user1’s tenant and whether they are part of the ‘admin’ role which has the ability to edit reportA. We can query FGA for this check from our code as follows:

Check if a user has a permission in an organization
List the permissions a user has in an organization

Summary

In this guide, we created a per-organization role based access control system for our B2B SaaS application using FGA. With this authorization model, our application can easily allow customers to create their own roles, assign organization-scoped permissions to those roles, and assign those roles to individual users in order to grant them permissions.