Data Model

FGA has five building blocks. Understanding how they fit together is the key to modeling authorization in your app.

Resources

A resource is a node in a tree. Every resource has a type, a parent (except root), and a name.

// SqlOSFgaResource
{
    Id: "chain_walmart",
    ParentId: "org::acme",
    Name: "Walmart",
    ResourceTypeId: "chain"
}

Resources form a hierarchy. Grants on parent resources inherit to all descendants. See Resource Hierarchy.

Subjects

A subject is the entity being authorized. SqlOS supports four subject types:

Type	Use case
user	Human users synced from AuthServer
agent	Automated bots or AI agents
service_account	Service-to-service access with API keys
user_group	Groups of users sharing permissions

See Subject Types.

Roles

A role is a named set of permissions. Define roles that map to your app's access patterns:

Role	Permissions
Company Admin	CHAIN_VIEW, CHAIN_EDIT, LOCATION_VIEW, LOCATION_EDIT, INVENTORY_VIEW, INVENTORY_EDIT
Store Manager	LOCATION_VIEW, LOCATION_EDIT, INVENTORY_VIEW, INVENTORY_EDIT
Store Clerk	INVENTORY_VIEW

See Roles.

Permissions

A permission is a capability key scoped to a resource type. Convention: RESOURCETYPE_ACTION in uppercase.

Permission	Resource type	Action
CHAIN_VIEW	chain	Read
CHAIN_EDIT	chain	Write
LOCATION_VIEW	location	Read
INVENTORY_EDIT	inventory	Write

See Permissions.

Grants

A grant links a subject, a role, and a resource. Because resources form a tree, a grant on a parent gives the subject that role on all descendants.

Subject: "jane"
Role: "Company Admin"
Resource: "org::acme"

→ jane can CHAIN_VIEW, CHAIN_EDIT on all chains under org::acme
→ jane can LOCATION_VIEW, LOCATION_EDIT on all locations under those chains
→ jane can INVENTORY_VIEW, INVENTORY_EDIT on all inventory items

See Grants.

How authorization works

When checking CHAIN_VIEW on chain_walmart:

1. Find all grants for the subject
2. For each grant, check if the role includes CHAIN_VIEW
3. Walk up from chain_walmart → org::acme → root
4. If any ancestor has a matching grant, access is allowed

This tree walk is performed by a SQL Server table-valued function, so it works inside EF Core queries without loading data into memory.