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 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

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

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

Admin Roles

When auth is configured, the admin user-management surface is always mounted (there is no separate toggle). Registering does not make anyone an admin — every sign-up receives defaultRole (member unless you set it). The first admin is created deliberately, by one of:

• the AUTH_ADMIN_EMAIL / AUTH_ADMIN_PASSWORD environment variables, applied at boot;
• the sovrium admin create <email> CLI;
• the one-time bootstrap-claim token printed at first start (see User Management).

After that, an existing admin promotes others with POST /api/auth/admin/set-role. 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 — a role change that would remove the last admin able to sign in is refused with 409.
• Impersonate users for support workflows — except other admins, who cannot be impersonated.
• 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.

Related Pages

• Authentication Overview — default roles in context.
• Groups — many-to-many membership layered on roles.
• Post-Login Landing — per-role landing rules.
• Table Permissions — where roles actually gate data.