WorkOS Docs Homepage
FGA
API referenceDashboardSign In
Getting StartedOverviewOverviewQuick StartQuick StartPlaygroundPlaygroundKey ConceptsSchemaSchemaWarrantsWarrantsResourcesResourcesPoliciesPoliciesQuery LanguageQuery LanguageWarrant TokensWarrant TokensOperations & UsageOperations & UsageManagementSchema ManagementSchema ManagementLocal DevelopmentLocal DevelopmentIdentity Provider SessionsIdentity Provider SessionsModelingOrg Roles & PermissionsOrg Roles & PermissionsCustom RolesCustom RolesGoogle DocsGoogle DocsEntitlementsEntitlementsUser GroupsUser GroupsManaged Service ProviderManaged Service ProviderAttribute-Based Access ControlAttribute-Based Access ControlConditional RolesConditional RolesPolicy ContextPolicy ContextPublic AccessPublic AccessSuperusersSuperusersBlocklistsBlocklists
API Reference
API Reference
Events
Events
Integrations
Integrations
Migrate to WorkOS
Migrate to WorkOS
SDKs
SDKs

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.

On this page

  • When to Use it
  • Schema
  • Example
    • 1. Apply the schema
    • 2. Create warrants
    • 3. Check access

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"
}
}
],
}'
© WorkOS, Inc.
FeaturesAuthKitSingle Sign-OnDirectory SyncAdmin PortalFine-Grained Authorization
DevelopersDocumentationChangelogAPI Status
ResourcesBlogPodcastPricingSecuritySupport
CompanyAboutCustomersCareersLegalPrivacy
© WorkOS, Inc.