Custom Roles

Allow B2B customers to create org-scoped custom roles and map them to a static set of permissions that grant capabilities in your application.

Explore the example from this guide in the FGA Playground, where you can interact with the schema, warrants, and access checks in real-time!

Customizable, role-based access control gives customers the freedom to define their own custom roles and map each one to a subset of the permissions offered by your application.

When to Use it

Implement custom roles when:

Role-based access control: Your application’s requirements call for role-based access control (RBAC).
Custom roles: Your customers need the ability to define custom roles that are scoped to their organization and map them to a static set of permissions in your application.

Schema

schema.txt

 version 0.3

type user

type role
  relation member [user]

type organization
  relation can_read_company_info [role]
  relation can_write_company_info [role]
  relation can_read_reports [role]
  relation can_write_reports [role]

  inherit can_read_company_info if
    any_of
      relation can_write_company_info
      relation member on can_read_company_info [role]

  inherit can_write_company_info if
    relation member on can_write_company_info [role]

  inherit can_read_reports if
    any_of
      relation can_write_reports
      relation member on can_read_reports [role]

  inherit can_write_reports if
    relation member on can_write_reports [role]

Example

1. Apply the schema

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.

Note: make sure to select the correct environment with the CLI

 workos fga schema apply schema.txt

2. Create warrants

Create warrants that associate organizations, roles, and users. The example schema defines the following relationships:

users with organizations
users with custom roles (e.g. org:acme:read-only)

Let’s create a few warrants between organization acme, role org:acme:read-only, and user user_2oDscjroNWtzxzYEnEzT9P7VYEe:

Create warrants

 curl "https://api.workos.com/fga/v1/warrants" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '[
    {
      "op": "create",
      "resource_type": "organization",
      "resource_id": "acme",
      "relation": "can_read_company_info",
      "subject": {
        "resource_type": "role",
        "resource_id": "org:acme:read-only"
      }
    },
    {
      "op": "create",
      "resource_type": "role",
      "resource_id": "org:acme:read-only",
      "relation": "member",
      "subject": {
        "resource_type": "user",
        "resource_id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe"
      }
    }
  ]'

3. Check access

With our environment setup, we can check the user’s permission to read company info.

Check if a user has a permission in their organization

 curl "https://api.workos.com/fga/v1/check" \
  -X POST \
  -H "Authorization: Bearer sk_example_123456789" \
  --data-raw \
  '{
    "checks": [
      {
        "resource_type": "organization",
        "resource_id": "acme",
        "relation": "can_read_company_info",
        "subject": {
          "resource_type": "user",
          "resource_id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe"
        }
      }
    ],
  }'