Roles
Manage user roles, primary and secondary group memberships, role colors, and default seeded groups.
In VitNode, a role groups users together for display styles (e.g. colored username badges) and staff permission grants.
Quick start
Resolve a user's complete set of role IDs (primary + secondary) on the API:
import { getUserRoleIds } from '@vitnode/core/api/lib/check-staff-permission'
const user = c.get('user')
const roleIds = user ? await getUserRoleIds(c, user) : []Seeded Default Roles
VitNode automatically seeds four protected system roles upon installation:
| Role | Flags | Default Color | Staff Privileges |
|---|---|---|---|
| Guest | guest | None | None (applies to unauthenticated visitors) |
| Member | default | None | Standard registered member role |
| Moderator | None | Green (hsl(122, 80%, 45%)) | Unrestricted moderation staff |
| Administrator | root | Red (hsl(0, 100%, 50%)) | Unrestricted administrative staff (root: true) |
First Account is Root
The first user to register during site initialization is automatically assigned the Administrator role.
Role Model Attributes
core_roles defines group styling and properties:
color: CSS color string (e.g.#ff0000,hsl(210, 100%, 50%)) applied to member usernames across the UI.prefix: An emoji or a Lucide icon rendered in front of the role name and in front of every member's username. Stored asemoji:🚀oricon:rocket- see the Emoji & Icon Picker for the codec and the components that read it.root: Whentrue, user bypasses all staff permission checks.default: The role automatically assigned to newly registered members.guest: Reserved for unauthenticated requests.
Primary vs Secondary Roles
Every user has exactly one primary role (stored in core_users.roleId). Users may additionally hold multiple secondary roles (stored in core_users_secondary_roles), inheriting combined staff permissions across all assigned groups.
AdminCP Role Management
Create, color-code, and organize user groups under Core → Roles (/admin/core/roles).
The General tab of the create/edit dialog carries both display fields: Color, which tints member usernames, and Prefix, which puts an emoji or an icon in front of them.