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

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.

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!

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