Fine-Grained Authorization (FGA)

Fine-Grained Authorization (FGA) extends the existing WorkOS RBAC system to handle the complex, fast-changing authorization needs of modern B2B SaaS products.

Most products start with simple, org-level roles like Admin and Member. As adoption grows, the model is forced to account for workspaces, projects, apps, pipelines, nested tenants, custom roles, group-based collaboration, and enterprise exceptions. What used to evolve over a decade can now change in 12 – 18 months. Teams patch RBAC with special cases, multiply role variants, and eventually face full rewrites.

FGA is designed as the next step in that evolution:

• It keeps the mental model of RBAC: roles, permissions, assignments.
• It adds hierarchical, resource-scoped access control.
• It integrates natively with existing WorkOS products, including RBAC, SSO, Directory Sync/SCIM, AuthKit, and IdP role mapping.
• It can be adopted incrementally with no data migration or confusing schema DSL.

The goal is to give SaaS teams a single authorization foundation that adapts as the product and customer requirements change, without introducing a parallel system or forcing conceptual rewrites.

FGA formalizes three building blocks:

• Subjects – Users, groups, devices, or agents that can be granted access.
• Resources – Business entities in your product (organizations, workspaces, projects, apps, etc.) arranged in a hierarchy.
• Privileges – Roles and the permissions contained within them.

The key shift from traditional, org-only RBAC is that resources and their hierarchy are first-class. Roles and permissions are scoped to specific resource types and may be assigned at any level of that hierarchy.

FGA’s resource model captures how entities in your application relate to one another. It is:

• Hierarchical – Up to five layers deep.
• Typed – Each layer can define multiple resource types.
• Single-parent – Each resource instance has exactly one parent (organization or another resource).

Typical hierarchies:

organization
└─ workspace
   └─ project
      └─ app

organization
└─ account
   └─ dashboard

organization
└─ team
   ├─ repository
   └─ pipeline

Resource types and their allowed parent/child relationships are defined in the WorkOS Dashboard. Examples:

• Organizations
• Workspaces
• Accounts
• Projects
• Applications
• Pipelines
• Spaces
• Repositories
• Dashboards

At runtime, your application registers resource instances as users create them:

Org:acme
 └─ Workspace:finance (ws_123)
     └─ Project:quarterly-plan
         └─ App:forecasting

Each instance has:

• A type (workspace, project, …).
• An id (ws_123).
• A parent (an organization or another resource instance).

This structure drives:

• Where roles can be assigned.
• How permissions inherit down the tree.
• How cascaded cleanup works when a resource is deleted.

The model is optimized for low-cardinality entities like workspaces, accounts, and apps. High-volume application objects – documents, messages, tasks, rows, and similar – should remain in your application’s own source of truth rather than being modeled as FGA resource instances. Syncing these objects into an external authorization store introduces latency, reconciliation issues, and operational overhead.

Some systems attempt to avoid this by querying your database during authorization (“local evaluation”), but this shifts the problem: authorization performance becomes tied to your production database, rule logic becomes tightly coupled to your schema, and developers must maintain custom query filters that scale poorly in multi-tenant environments. Modeling inheritance or hierarchy must also be done manually, which becomes brittle as products evolve.

FGA avoids both patterns. High-cardinality objects remain in your database, but can still participate in authorization by storing a reference to their nearest FGA-managed parent resource. Your application passes that parent during checks, allowing permissions to be evaluated through the hierarchy without syncing every object or embedding authorization logic in database queries.

This keeps authorization fast, predictable, and decoupled from your data model – without the trade-offs required by other approaches.

Roles and permissions in FGA are always defined relative to a resource type. This means a role created for a workspace applies only to workspace resources, a project role applies only to projects, and so on. Existing organization-level RBAC roles continue to function exactly as they do today and are automatically scoped to the organization.

A role describes what a subject can do within the scope of a particular resource type. Each role contains one or more permissions, and those permissions may apply either to:

• the same resource type as the role (for example, workspace:view), or
• a child resource type (for example, project:edit), enabling permission inheritance down the hierarchy.

If a role is scoped to a workspace type, it can grant permissions such as viewing or editing that workspace. If it includes child-type permissions (like project-level actions) those permissions automatically apply to all child resources under that workspace. This prevents role explosion and allows a single workspace-level role to control access across the entire sub-tree beneath it.

Example:

• An Organization Member role grants organization-level permissions such as viewing the org or accessing its workspaces.
• A Workspace Admin role grants full access to a specific workspace and all projects within it.
• A Project Editor role grants edit rights only to a particular project and its apps, without affecting sibling projects.

Through this model, FGA ensures permissions are predictable, type-safe, and aligned with the structure of your application’s resource hierarchy – while preserving all existing RBAC behavior.

An assignment binds:

• An Organization Membership (user)
• A role
• An Organization or resource instance

When a role includes child-type permissions, FGA automatically propagates those permissions down to children under that parent resource.

Consider the following hierarchy:

Org
  └─ Account
       └─ App

We can configure roles at each level to define the following access patterns:

• A user is Member of Org:1 with org:view, account:view, and app:view permissions. They can view the organization, all of its accounts, and all apps under those accounts.
• The same user is Account Editor for Account:B and can edit that account and all of its apps.
• A user is App Editor for App:Finance and can edit only that app instance.
• Another user is Account Read-Only on Account:A and can view only that account, not its apps.

AuthKit continues to embed organization-level roles and permissions in access tokens. These roles come from the existing RBAC product and may also include any resource-scoped permissions defined within those org-level roles. They remain the best mechanism for coarse-grained checks – for example, determining whether a user can access an organization at all or perform billing-related actions.

To evaluate access on a specific resource instance, your application calls the Authorization API:

POST /authorization/check

The check engine considers:

• Direct assignments on workspace:ws_123.
• Assignments on parent resources (e.g., a workspace role inheriting from an org assignment).
• Organization-level roles from the session token that contain permissions for the relevant resource type.

FGA is exposed through a set of Authorization API endpoints grouped into three concerns: resources, assignments, and access checks.

• GET /authorization/resources
• POST /authorization/resources
• PATCH /authorization/resources/{type}/{id}
• DELETE /authorization/resources/{type}/{id}

• POST/DELETE /authorization/assignments

• POST /authorization/check
• GET /authorization/resources/{type}/{id}/organization_memberships
• GET /authorization/organization_memberships/{membership_id}/resources
• GET /authorization/organization_memberships/{membership_id}/roles

With resource discovery endpoints, you can implement queries that align with common product features, such as:

• “List members with access to this workspace”
• “All projects under a parent workspace this user can edit”
• “List all assigned roles for a user”

FGA integrates directly with SSO, Directory Sync, and IdP role/attribute mapping. Organizations can:

• Map IdP groups to resource-level roles, so teams inherit the correct workspace or project access automatically.
• Use IdP attributes to drive assignments, ensuring roles reflect organizational metadata such as department or job function.
• Align internal team structures with FGA resource types, allowing identity changes in the IdP to cascade cleanly across the application’s authorization model.

Coordinating identity information with a hierarchical authorization system is one of the hardest challenges in modern SaaS architecture – and FGA provides a unified solution that no other provider offers today.

FGA is designed for real-time authorization and heavily optimized. It uses the resource hierarchy to efficiently evaluate permissions, ensuring accurate and fast access decisions.

Key performance characteristics:

• Sub-50 ms p95 access checks.
• Strong consistency.
• High availability.
• Warmed caches.
• Edge caches for low-latency global access (scheduled for a future release).

FGA works alongside the existing RBAC product:

• No migrations are required.
• Existing RBAC roles and organization memberships continue working.
• You can adopt FGA incrementally.

A typical rollout:

1. Use current RBAC for org-level access.
2. Define resource types to mirror your product structure.
3. Begin registering resource instances.
4. Introduce scoped roles like workspace_admin or project_editor.
5. Replace custom logic with Authorization API checks.
6. Map IdP groups and attributes to resource-scoped roles.

High cardinality resource types introduce a subtle but serious anti-pattern in Zanzibar inspired systems: syncing millions of rapidly changing resource instances to an external authorization system. As cardinality increases, so does the likelihood of data inconsistencies and update failures, especially when resources sit in the application’s hot path. Pushing resource updates over the network to a third-party system adds latency and instability in the application’s critical path.

WorkOS FGA takes a different approach. Instead of treating every individual resource as an external entity that must be synced, applications store high-cardinality resource types locally and register only the stable parent resource types inside WorkOS. This keeps authorization fast, consistent, and close to the application’s core workflows while offloading complex hierarchy management to WorkOS. The result is an expressive model that avoids remote bottlenecks and an architecture that stays performant, resilient, and easy to evolve as the product grows.

If you are interested in participating in the restricted preview, please reach out to WorkOS support.