Skip to main content
Authorization is application-specific. In an organization with multiple teams building different applications or modules, each team should be able to define and evolve their authorization policies independently. Modular models allows splitting your authorization model across multiple files and modules, improving upon some of the challenges that may be faced when maintaining an authorization model within a company, such as:
  • A model can grow large and difficult to understand.
  • As more teams begin to contribute to a model, the ownership boundaries may not be clear and code review processes might not scale.
With modular models, a single model can be split across multiple files in a project and organized in a way that makes sense for the project or teams collaborating on it. For example, modular models allows ownership for reviews to be expressed using a feature like GitHub’s, GitLab’s or Gitea’s code owners.

​
Key Concepts

​
fga.mod

The fga.mod file is the project file for modular models. It specifies the schema version for the final combined model and lists the individual files that make up the modular model.

​
Modules

OpenFGA modules define the types and relations for a specific application module or service. Modules are declared using the module keyword in the DSL, and a module can be written across multiple files. A single file cannot have more than one module.

​
Type Extensions

As teams implement features, they might find that core types they are dependent upon might not contain all the relations they need. However, it might not make sense for these relations to be owned by the owner of that type if they aren’t needed across the system. Modular models solves that problem by allowing individual types to be extended within other modules to to share those relations. The following are requirements for type extension:
  • The extended type must exist
  • A single type can only be extended once per file
  • The relations added must not already exist, or be part of another type extension

​
Example

The following example shows how an authorization model for a SaaS company with issue-tracking and wiki software can implement modular models.

​
Core

If there is a core set of types owned by a team that manages the overall identity for the company, the following provides the basics: users, organizations and groups that can be used by each product area.

​
Issue tracking

The issue tracking software separates out the project- and issue-related types into separate files. Below, we also extend the organization type to add a relation specific to the issue tracking feature: the ability to authorize who can create a project.

​
Wiki

The wiki model is managed in one file until it grows. We can also extend the organization type again to add a relation tracking who can create a space.

​
fga.mod

To deploy this model, create the fga.mod manifest file, set a schema version, and list the individual module files that comprise the model.

​
Putting it all together

With individual parts of the modular model in place, write the model to OpenFGA and run tests against it. Below is an example of what to run in the CLI:
This model can now be queried and have tuples written to it, just like a singular file authorization model.

​
Viewing the model

When using the CLI to view the combined model DSL with fga model get --store-id=$FGA_STORE_ID, the DSL is annotated with comments defining the source module and file for types, relations and conditions. For example, the organization type shows that the type is defined in the core.fga file as part of the core module, the can_create_project relation is defined in issue-tracker/projects.fga as part of the issuer-tracker module, and the can_create_space relation is defined in the wiki.fga file as part of the wiki module.
Last modified on September 28, 2026