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

User Groups

Learn how to make user group abstractions to manage permissions at scale.

On this page

  • When to Use It?
  • Example Applications
  • 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!

User groups in Fine-Grained Authorization (FGA) allow you to manage permissions at scale by grouping users and granting access to those groups. This is particularly useful in large organizations where managing individual user permissions can become cumbersome.

When to Use It?

You should consider using user groups in the following scenarios:

  • Large Organizations: When you have a large number of users and resources, managing permissions individually can be inefficient.
  • Dynamic User Base: If your user base changes frequently (e.g., employees joining or leaving), management groups can simplify the process of updating permissions.
  • Hierarchical Structures: When your organization has a hierarchical structure (e.g., departments, teams), management groups can help you define permissions at different levels of the hierarchy without duplicating effort.

Example Applications

Management groups can be applied in various scenarios, including:

  • Enterprise Applications: In large enterprises, you can create groups for different departments (e.g., Sales, Engineering) and assign permissions to these groups rather than individual users.
  • Multi-Tenant SaaS Applications: For SaaS applications serving multiple organizations, you can create groups for each tenant and manage permissions for users within those tenants.

Schema

version 0.3
type user
type organization
relation admin [user]
relation document_viewer [user]
relation document_manager [user]
inherit document_manager if
relation admin // admins are also document managers
inherit document_viewer if
relation document_manager // document managers are also viewers
type document
// A document has a parent organization
relation parent [organization]
relation edit [user]
relation view [user]
// Allow users to edit the document if they
// are in the document manager group on the organization that owns it
inherit edit if
relation document_manager on parent [organization]
// Allow users to view the document if they
// are in the document viewer group on the organization that owns it
inherit view if
relation document_viewer on parent [organization]

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 and documents. Add a users to a document_viewer / document_manager groups.

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": "document_manager",
"subject": {
"resource_type": "user",
"resource_id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe"
}
},
{
"op": "create",
"resource_type": "organization",
"resource_id": "acme",
"relation": "document_viewer",
"subject": {
"resource_type": "user",
"resource_id": "user_3kLwpXyzQTuvbNApRmC5X4ZhAmd"
}
},
{
"op": "create",
"resource_type": "document",
"resource_id": "document-1",
"relation": "parent",
"subject": {
"resource_type": "organization",
"resource_id": "acme"
}
}
]'

3. Check access

With our environment setup, we can check the user’s permission to view items.

Check if a user can view a document
curl "https://api.workos.com/fga/v1/check" \
-X POST \
-H "Authorization: Bearer sk_example_123456789" \
--data-raw \
'{
"op": "all_of",
"checks": [
{
"resource_type": "document",
"resource_id": "document-1",
"relation": "edit",
"subject": {
"resource_type": "user",
"resource_id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe"
},
"context": {}
},
{
"resource_type": "document",
"resource_id": "document-1",
"relation": "view",
"subject": {
"resource_type": "user",
"resource_id": "user_3kLwpXyzQTuvbNApRmC5X4ZhAmd"
},
"context": {}
}
]
}'
© WorkOS, Inc.
FeaturesAuthKitSingle Sign-OnDirectory SyncAdmin PortalFine-Grained Authorization
DevelopersDocumentationChangelogAPI Status
ResourcesBlogPodcastPricingSecuritySupport
CompanyAboutCustomersCareersLegalPrivacy
© WorkOS, Inc.