Org Roles & Permissions

Create org-scoped roles based on common user personas 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!

Build a role-based access control (RBAC) that scopes each user’s role and permission assignments to a specific organization.

When to Use it

Implement org roles and permissions when:

Role-based access control: Your application’s requirements call for role-based access control (RBAC)
Org-specific roles: Your customers want to grant their users privileges based on their role within a specific organization.

Schema

schema.txt

 version 0.3

type user

type organization
    relation role_admin [user]
    relation role_read_only [user]
    inherit role_read_only if
        relation role_admin

    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 role_read_only

    inherit can_write_company_info if
        relation role_admin

    inherit can_read_reports if
        any_of
            relation can_write_reports
            relation role_read_only

    inherit can_write_reports if
        relation role_admin

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": "role_admin",
      "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"
        }
      }
    ],
  }'