Role-Based Access Control (RBAC)

Role-Based Access Control (RBAC) grants permissions to users based on the roles they hold. Permify Schema lets you model RBAC at different levels of granularity — from simple global roles attached to an organization all the way to fully custom, assignable role objects.

Global Roles
Resource-Specific Roles
Custom Roles

Global Roles

Global roles live on the highest-level entity (typically organization) and are shared across every resource that entity owns. This is the simplest starting point for RBAC.

Define the user entity

Every Permify schema requires a user entity. It is intentionally empty — other entities reference it as a relation type.

entity user {}

Add roles to the organization

Roles are modeled as relations on the entity where they live. Here we define four roles: admin, member, manager, and agent.

entity organization {

    // roles
    relation admin   @user
    relation member  @user
    relation manager @user
    relation agent   @user

}

Define permissions using boolean operators

Permissions combine roles with or, and, and not operators.

entity organization {

    // roles
    relation admin   @user
    relation member  @user
    relation manager @user
    relation agent   @user

    // organization file permissions
    permission view_files        = admin or manager or (member not agent)
    permission delete_file       = admin

    // vendor file permissions
    permission view_vendor_files  = admin or manager or agent
    permission delete_vendor_file = agent

}

view_files — admins, managers, or members who are not agents.
delete_file — admins only.
view_vendor_files — admins, managers, or agents.
delete_vendor_file — agents only.

Global role permissions defined on organization apply uniformly to everything owned by that organization. Move to Resource-Specific Roles when different resources need different permission sets.

Resource-Specific Roles

Resource-specific roles extend global roles by attaching permissions directly to resource entities (file, vendor, etc.) and referencing the organization’s roles through relation traversal (org.admin, org.manager, …).

Keep roles on the organization

Organization roles remain the source of truth. Resource entities reference them rather than redefining them.

entity user {}

entity organization {
    relation admin   @user
    relation member  @user
    relation manager @user
    relation agent   @user
}

Define the file entity with resource-specific permissions

The file entity has its own owner relation and inherits organizational roles via org.*.

entity file {
    // resource-specific relations
    relation owner  @user
    relation org    @organization
    relation vendor @vendor

    // resource-specific permissions
    permission view   = org.admin or org.manager or (org.member not org.agent) or owner
    permission edit   = org.admin or org.manager or owner
    permission delete = org.admin or owner
}

Define the vendor entity with its own permission set

entity vendor {
    // vendor-specific relations
    relation primary_contact @user
    relation org             @organization

    // vendor-specific permissions
    permission manage = org.admin or org.agent
    permission view   = org.admin or org.manager or org.agent or primary_contact
}

Complete Schema

entity user {}

entity organization {
    relation admin   @user
    relation member  @user
    relation manager @user
    relation agent   @user
}

entity file {
    relation owner  @user
    relation org    @organization
    relation vendor @vendor

    permission view   = org.admin or org.manager or (org.member not org.agent) or owner
    permission edit   = org.admin or org.manager or owner
    permission delete = org.admin or owner
}

entity vendor {
    relation primary_contact @user
    relation org             @organization

    permission manage = org.admin or org.agent
    permission view   = org.admin or org.manager or org.agent or primary_contact
}

Traversing relations with dot notation (e.g. org.admin) lets child resources inherit roles from parent entities without duplicating role definitions.

Custom Roles

Custom roles let you create named role objects at runtime (e.g. role:admin, role:member) and assign specific permissions to them without hardcoding role names in the schema. This pattern is useful when roles must be configurable by end-users.

Model the role entity

The role entity has a single assignee relation pointing to users. Each role instance (e.g. role:admin) is a first-class object.

entity user {}

entity role {
    relation assignee @user
}

Attach role assignees to resource permissions

Instead of referencing @user directly, resource entities reference @role#assignee. This means “users who are assignees of some role”.

entity dashboard {
    relation view @role#assignee
    relation edit @role#assignee
}

entity task {
    relation view @role#assignee
    relation edit @role#assignee
}

Write relationships to define the custom roles

Create role instances and bind them to resource permissions by writing relationship tuples.

dashboard:145#view@role:admin#assignee
dashboard:145#view@role:member#assignee
dashboard:145#edit@role:admin#assignee

task:5621#view@role:admin#assignee
task:5621#view@role:member#assignee
task:5621#edit@role:admin#assignee

The resulting permission matrix:

Permission	admin	member
dashboard:view	✅	✅
dashboard:edit	✅	⛔
task:view	✅	✅
task:edit	✅	⛔

Assign users to roles

Assign a user to a role by writing an assignee relationship.

role:member#assignee@user:1

Now user:1 inherits every permission granted to role:member.

Checking Permissions

{
  "metadata": {
    "schema_version": "",
    "snap_token": "",
    "depth": 20
  },
  "entity": {
    "type": "dashboard",
    "id": "145"
  },
  "permission": "view",
  "subject": {
    "type": "user",
    "id": "1",
    "relation": ""
  }
}

view on dashboard:145 → Allow — user:1 is an assignee of role:member, which has the view permission.
edit on dashboard:145 → Deny — user:1 is not an assignee of role:admin.

The custom roles pattern separates role definitions from schema changes. You can create new roles, modify their permissions, or delete them entirely by writing or deleting relationship tuples — no schema redeploy needed.

Full Working Schema

The schema below combines all three RBAC patterns into a single coherent model: global roles on organization, resource-specific permissions on file and vendor, and a custom role entity for fine-grained runtime control.

entity user {}

// Custom role entity — role instances are created at runtime
entity role {
    relation assignee @user
}

// Global organizational roles
entity organization {
    relation admin   @user
    relation member  @user
    relation manager @user
    relation agent   @user
}

// Resource-specific permissions inherit organization roles
entity file {
    relation owner  @user
    relation org    @organization
    relation vendor @vendor

    permission view   = org.admin or org.manager or (org.member not org.agent) or owner
    permission edit   = org.admin or org.manager or owner
    permission delete = org.admin or owner
}

entity vendor {
    relation primary_contact @user
    relation org             @organization

    permission manage = org.admin or org.agent
    permission view   = org.admin or org.manager or org.agent or primary_contact
}

// Dashboard and task use the custom-role pattern
entity dashboard {
    relation view @role#assignee
    relation edit @role#assignee
}

entity task {
    relation view @role#assignee
    relation edit @role#assignee
}

Overview

Getting Started

Modeling Guides

Deployment & Configuration

Operations

Use Cases

Role-Based Access Control (RBAC)

Global Roles

Resource-Specific Roles

Complete Schema

Custom Roles

Checking Permissions

Full Working Schema

Build docs developers (and LLMs) love

Overview

Getting Started

Modeling Guides

Deployment & Configuration

Operations

Use Cases

​Global Roles

​Resource-Specific Roles

​Complete Schema

​Custom Roles

​Checking Permissions

​Full Working Schema

Build docs developers (and LLMs) love

Global Roles

Resource-Specific Roles

Complete Schema

Custom Roles

Checking Permissions

Full Working Schema