Roles & Hierarchy | ShipSaaS Documentation | ShipSaaS

The boilerplate includes a hierarchical role system where higher roles inherit permissions from lower roles, providing flexible and scalable access control.

Perfect for: Team management, progressive access levels, and enterprise role structures.

Role Hierarchy

The boilerplate includes a hierarchical role system where higher roles inherit permissions from lower roles:

SUPER_ADMIN  ← Highest level (all permissions)
    ↑
  ADMIN      ← Admin panel access
    ↑
REDACTOR     ← Content management
    ↑
MODERATOR    ← Community management
    ↑
  USER       ← Basic authenticated user
    ↑
 GUEST       ← Unauthenticated user

Role inheritance: A MODERATOR automatically has all USER permissions, an ADMIN has all MODERATOR + USER permissions, etc.

Role Descriptions

Unauthenticated usersPermissions:

View public content
Access landing pages
Use login/register forms
Read documentation

Cannot: Access any protected features

Role Management

Assigning Roles

// Admin function to assign roles
export async function assignRole(userId: string, newRole: Role) {
  // Verify current user has permission to assign roles
  const currentUser = await getCurrentUser()
  const ability = await definePermissions(currentUser)

  if (!ability.can('manage', 'User')) {
    throw new Error('Insufficient permissions to assign roles')
  }

  // Update user role
  await updateUserRole(userId, newRole)

  // Log role change for audit
  await logRoleChange({
    userId,
    oldRole: user.role,
    newRole,
    assignedBy: currentUser.id
  })
}

Role Hierarchy Validation

// Ensure role hierarchy is respected
export function canAssignRole(assignerRole: Role, targetRole: Role): boolean {
  const roleHierarchy = {
    'GUEST': 0,
    'USER': 1,
    'MODERATOR': 2,
    'REDACTOR': 3,
    'ADMIN': 4,
    'SUPER_ADMIN': 5
  }

  const assignerLevel = roleHierarchy[assignerRole]
  const targetLevel = roleHierarchy[targetRole]

  // Can only assign roles lower than or equal to your own
  return assignerLevel >= targetLevel
}

Common Role Scenarios

Typical use cases for each role:

GUEST (Public Users):

Marketing website visitors
Potential customers browsing features
Users reading documentation

USER (Customers):

Paying subscribers
Individual users of SaaS features
Personal account management

MODERATOR (Community Managers):

Forum moderators
Content reviewers
Customer support agents

REDACTOR (Content Creators):

Blog writers
Content managers
Marketing team members

ADMIN (System Administrators):

IT administrators
Business managers
Billing administrators

SUPER_ADMIN (System Owners):

Company founders
Technical leads
System architects

Best Practices

Start with minimal roles

Begin with USER and ADMIN, add others as needed.

Document role permissions

Keep clear documentation of what each role can do.

Regular role audits

Review and update user roles periodically.

Principle of least privilege

Give users the minimum role needed for their tasks.

Role system ready! Your application now has a clear, hierarchical role structure that scales with your business needs.