Skip to main content

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 a type and a globally unique id. A resource can optionally point to a parent.
You register resources with createResource. The engine validates that the parent exists before accepting a child.
Resource ids are unique across all types (the id is the primary key), so 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 has inheritFromParent 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 passing permissionRules to the config:
You can also limit which permissions inherit by passing an array:

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. Use subjectType: '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

The maxDepth 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.

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.
Last modified on October 18, 2026