Skip to main content
View as Markdown

Roles & RBAC

Sovrium uses role-based access control (RBAC) with an optional layer of groups. Every authenticated user has exactly one role; roles are arranged in a numeric hierarchy; and table permissions reference roles to gate create/read/update/delete and per-field access.

auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member
  roles:
    - name: editor
      description: Can edit content
      level: 30

Built-in Roles

Three roles ship with every auth-enabled app. They are always available and cannot be redefined by custom roles.

Role Level Access
admin 80 Full access — manage users, roles, and settings; all permissions.
member 40 Standard access to application resources.
viewer 10 Read-only access.

Role Hierarchy & Levels

Each role has a numeric level. Higher levels are more privileged. The level establishes an ordering used by permission resolution and by features that compare role seniority (for example, an admin-equivalent role is one at the highest configured level).

Built-in levels are fixed at admin=80, member=40, viewer=10. Custom roles slot anywhere along this scale via their own level:

auth:
  roles:
    - name: editor
      level: 30 # between viewer (10) and member (40)
    - name: moderator
      level: 50 # between member (40) and admin (80)

Custom Role Definitions

auth.roles is an array of custom role definitions layered on top of the built-ins. An empty array (or omitting the field) means only the built-in roles exist.

auth:
  roles:
    - name: editor
      description: Can edit content
      level: 30
    - name: moderator
      level: 20
    - name: contributor
Property Description
name Required. Role identifier. Lowercase, alphanumeric, hyphens; must start with a letter. Must be unique and must not collide with a built-in role name or a group name.
description Human-readable description of the role's purpose.
level Hierarchy level (higher = more privileged). Built-in references: admin=80, member=40, viewer=10.
defaultLanding Per-role post-login landing URL. See Post-Login Landing.
pickerLanding Multi-record fallback for a templated defaultLanding. See Post-Login Landing.

Naming rules — role names match ^[a-z][a-z0-9-]*$:

Name Valid? Reason
editor ✅ lowercase letters
content-manager ✅ hyphen allowed
Editor ❌ uppercase not allowed
123role ❌ must start with a letter

Validation rejects:

  • Duplicate custom role names.
  • Custom names that collide with built-in roles (admin, member, viewer).
  • Custom names that collide with a group name (roles and groups share a namespace).

Default Role

auth.defaultRole is the role assigned to new users on registration. It defaults to member when omitted, and must reference a built-in role or a custom role defined in auth.roles.

auth:
  strategies:
    - type: emailAndPassword
  defaultRole: viewer # new users start read-only
  roles:
    - name: editor
      level: 30
Property Description
defaultRole Role granted to newly registered users. Built-in or custom name. Defaults to member.

Admin Roles

When auth is configured, the admin user-management surface is always mounted (there is no separate toggle). The first user to register becomes an admin (firstUserAdmin). Admins can:

  • Create users (POST /api/auth/admin/create-user) — including when allowSignUp: false.
  • Invite users with single-use tokens (POST /api/auth/admin/invite-user).
  • Assign and change roles.
  • Impersonate users for support workflows.
  • Ban / unban users.

The highest-level role is treated as admin-equivalent for these checks, so a custom role at level: 80 (or higher) participates in admin gating alongside the built-in admin role.

How Roles Gate Data

Roles do not grant data access on their own — they are referenced by each table's permissions block. A role with no matching permission entry has no access to that table. See Table Permissions for the full create/read/update/delete/restore/comment and per-field model, including how group:-prefixed entries combine with roles.