Why ReBAC
Traditional RBAC assigns roles to users globally or per-org. That works until you need finer-grained questions like “can agent X view this specific document because it belongs to a project in a workspace where X is an editor?” RBAC flattens that into a single role check and loses the context. ReBAC models authorization as a graph. Subjects (users, agents, teams) connect to objects (orgs, workspaces, projects, documents) through typed relationships. Permission checks walk the graph, following direct relationships and parent-child inheritance. This is the same approach Google uses internally (Zanzibar) and what WorkOS FGA, Ory Keto, and SpiceDB implement. theAuth ships a built-in ReBAC engine that works with agents as first-class subjects.Quick start
Resource hierarchy
Resources form a tree. Each resource has atype and a globally unique id. A resource can optionally point to a parent.
createResource. The engine validates that the parent exists before accepting a child.
document:spec and project:spec cannot both exist. Deleting a resource cascades: all child resources and the relationships that name the resource as subject or object are removed. Methods return a Result ({ success, data } or { success: false, error }) rather than throwing for expected failures such as PARENT_NOT_FOUND, RESOURCE_EXISTS, or RELATIONSHIP_EXISTS.
Relationships
A relationship is a tuple:(subjectType, subjectId, relation, objectType, objectId). Subjects can be users, agents, teams, or any string type you define.
Permission checks
check answers “does this subject have this permission on this object?” It returns { allowed: boolean, path?: string[] } where path shows the traversal steps when access is granted.
The engine resolves permissions in two ways:
Implied relations
For each resource type, some relations imply others. The built-in rules:
Any type not in this table (for example
doc) has no implication or inheritance rules: only a tuple whose relation equals the requested permission grants access. Inheritance from the parent is on for workspace, project, document, and resource, and off for org.
So if you’re an editor on a document, a check for viewer succeeds. If you’re an owner, both editor and viewer checks succeed.
Parent inheritance
When a resource type hasinheritFromParent enabled (see the defaults above), the engine walks up the tree through the parent links stored by createResource. If Alice is a viewer on workspace eng, she’s also a viewer on project api (a child of eng) and document spec (a grandchild).
This combines with implied relations. Alice as editor on workspace eng gets viewer access to everything underneath.
Custom permission rules
Override the defaults by passingpermissionRules to the config:
Listing and expansion
List objects
Find all objects of a type that a subject can access:List subjects
Find all subjects that have a permission on an object:Expand
Get all relationships for an entity (as both subject and object):Agent integration
Agents are first-class subjects. UsesubjectType: 'agent' with the agent’s ID:
theauth.authorize() does not consult ReBAC. To combine the two, set relation on a permission and call theauth.policy.evaluate(), which runs the check for you (see Policy engine). Two limits apply there: the policy engine builds its own ReBAC module with the default rules only, so custom permissionRules are not used, and the requested resource must be a concrete type:id.
Depth limiting
ThemaxDepth config caps how many parent hops the engine will traverse; a check that would go deeper returns allowed: false. Default is 10. Set it lower if your hierarchy is shallow and you want faster checks:
Comparison with alternatives
theAuth ReBAC is opinionated toward the common hierarchy pattern (org > workspace > project > resource) with sensible defaults. Zanzibar and SpiceDB are more general but require you to write a schema DSL. WorkOS FGA is SaaS-only.
Related
Policy engine
Unified RBAC, ABAC, and ReBAC evaluation behind one evaluate() call.
Permissions
Direct resource-action permissions that complement ReBAC relationships.
Delegation
Agent-to-agent permission delegation with depth and expiry.
Multi-tenant
Tenant isolation that pairs with org-scoped ReBAC hierarchies.