User Roles and Role Hierarchy

Roles are the foundation of Raytio's access control model. Every user is assigned one or more roles, and those roles determine what the user can do, what they can see, and what appears in their UI. Roles are organised into a hierarchy where child roles inherit from parent roles, creating a layered permission structure.

Role types

Each role has a role_type that classifies what kind of access it represents:

Role type	Purpose
ABSTRACT	Organisational grouping roles that are not assigned directly to users. Used to structure the hierarchy (e.g. "Tenant staff", "External user").
JOB	Job-function roles that represent a position or responsibility (e.g. "CRM administrator", "Billing user").
DUTY	Duty roles that represent a specific responsibility or task area.
DATA	Data-access roles that control access to specific data sets or record types.

Role types help administrators understand the purpose of each role when managing assignments, but the system treats all types equally for permission evaluation — what matters is the role's position in the hierarchy and the permissions attached to it.

Role identity

Every role has several identifying fields:

• role_name — the unique machine-readable name within the tenant (e.g. crm_administrator)
• role_common_name — a human-readable display name (e.g. "CRM Administrator")
• role_distinguished_name — a fully qualified name for unambiguous identification
• role_description — a free-text description of the role's purpose

When a role is renamed, the platform keeps related access relationships consistent automatically.

Role hierarchy

Roles are connected through parent-child relationships. The hrm_user_role_parents view exposes these relationships for reporting and review. A role can have multiple parents and multiple children, forming a directed acyclic graph.

How inheritance works

When a role has a parent, the child role inherits all permissions and access from the parent. This means:

• A "CRM Administrator" who inherits from "CRM User" automatically receives everything "CRM User" can do, plus any additional permissions defined on "CRM Administrator" itself.
• Inheritance is transitive — if A inherits from B and B inherits from C, then A inherits from both B and C.
• The hierarchy is resolved automatically, so access inherited through multiple parent roles is included in each access decision.

The four-tier pattern

The default role hierarchy follows a four-tier pattern within each functional domain:

1. Administrator — full control over the domain (e.g. CRM Administrator)
2. User — standard operational access (e.g. CRM User)
3. Viewer — read-only access (e.g. CRM Viewer)
4. Base role — minimal access inherited by all roles in the category (Tenant Staff for internal, External User for external)

This pattern is repeated across functional domains where the tenant needs layered access. The exact role catalogue is reference data and may change as modules are added, renamed, or configured for a tenant.

User role assignments

A user is linked to roles through user role assignments. Each assignment connects a user to a role within the current tenant.

• A user can hold multiple roles simultaneously.
• When a user is assigned to a role, the platform treats the user as a member of that role group.
• The authorization model then resolves the full set of roles the user belongs to, including all inherited roles, when evaluating access checks.

note

Roles are tenant-scoped. A user who belongs to multiple tenants may hold different roles in each tenant.

Functional domain examples

Roles are commonly organised around product and operational domains. Examples include:

• Customer relationship management roles, such as CRM administrator, user, or viewer roles
• Billing, pricing, and accounts receivable roles for commercial operations
• Security, administration, and platform roles for tenant management
• Project roles, such as project administrator, user, or viewer roles
• External user roles for people who access tenant data from outside the organisation

These are examples, not a definitive list. The maintained role catalogue should live in reference data or a dedicated reference page. Each domain follows the four-tier pattern where applicable, with internal roles ultimately inheriting from "Tenant Staff" and external roles inheriting from "External User."

Relationship to other concepts

• Permissions are attached to roles via role–permission assignments. See Permissions.
• Authorization policies can target either individual users or roles. See Authorization Policies.
• Menus are assigned to roles to control UI visibility. See Role Menus.
• Role groups mirror the role hierarchy for relationship-based access. See Role Groups and Inheritance.