Roles and Permissions

Understand the RBAC (Role-Based Access Control) system in Testify, including the seven built-in roles, permission management, and how to assign roles to users.

Overview

Testify uses a granular role-based access control system to determine what each user can see and do. Every user is assigned one or more roles, and each role has a set of permissions that control access to features, data, and administrative functions.

The Seven Built-In Roles

Testify ships with seven predefined roles, organized in a hierarchy from most to least privileged.

1. Super Admin

The highest-level role with unrestricted access across the entire platform.

• Manage all organizations and tenants
• Create, update, and delete organizations
• Access all user data regardless of tenant
• Configure global prompts and AI settings
• Manage billing, subscriptions, and credits
• View audit logs across all organizations
• Manage roles and permissions
• Override tenant isolation for support purposes

Tip: The Super Admin role should be reserved for platform operators. It bypasses all tenant isolation rules.

2. Org Owner

The owner of an organization, typically the person who registered it.

• Full control over their organization's settings
• Manage all users within the organization (teachers and students)
• View organization-wide analytics and reports
• Configure organization branding and white-label settings
• Generate invite links for any role
• Cannot manage other Org Owners or Super Admins

3. Org Admin

An administrative role within an organization, granted by the Org Owner.

• Manage teachers and students (add, edit, remove)
• View organization users and their activity
• Access organization settings and branding
• Generate invite links for teachers and students
• View organization analytics
• Cannot manage other Org Admins, Org Owners, or Super Admins

4. Teacher

The primary content creator and exam administrator role.

• Create and manage questions in the question bank
• Build papers and exams
• Assign exams to classes and students
• Grade submissions and provide feedback
• View class-level and student-level analytics
• Generate invite links for students
• Manage their assigned classes
• Use AI features for question generation

5. Student

The learner role with access to exams, practice, and results.

• Take assigned exams
• View exam results and analytics
• Access practice mode and AI tutor
• View certificates and achievements
• Participate in gamification features (leaderboard, badges, streaks)
• Generate parent link codes

6. Parent

A monitoring role that provides read-only visibility into linked students' performance.

• View linked children's exam results
• Access performance reports and report cards
• See subject-wise analytics and improvement areas
• Monitor attendance and engagement
• Compare multiple children's performance
• Cannot modify any data or take exams

7. Reseller

A partner role for managing multiple organizations.

• Create and manage sub-organizations
• Configure white-label branding for clients
• Allocate credits and manage billing
• View revenue analytics across managed organizations
• Access reseller-specific dashboard

Viewing All Roles

1. Navigate to "Admin" > "Roles & Permissions"
2. The roles list displays:
   • Role name and shortname
   • Description
   • Sort order (determines hierarchy display)
   • Creation date

Creating a Custom Role

Super admins can create additional roles beyond the seven defaults.

1. Go to "Admin" > "Roles & Permissions"
2. Click "Create Role"
3. Enter the following:
   • "Role Name" -- a descriptive name (e.g., "Department Head")
   • "Description" -- what this role is for
4. Click "Save"

The system automatically generates a shortname from the role name (lowercase, no spaces) and assigns the next sort order value.

Tip: Custom roles start with no permissions. You must assign permissions after creation.

Updating a Role

1. Go to "Admin" > "Roles & Permissions"
2. Click on the role you want to edit
3. Update the "Name" or "Description"
4. Click "Save"

Tip: Changing a role name does not affect users already assigned to it. The shortname (used internally) is not changed when you rename a role.

Deleting a Role

1. Go to "Admin" > "Roles & Permissions"
2. Click the "Delete" button next to the role
3. Confirm the deletion

Deleting a role also removes all permission assignments for that role. Users previously assigned this role will lose those permissions.

Tip: Never delete the built-in roles (Super Admin, Org Owner, Org Admin, Teacher, Student, Parent, Reseller). This can break the system.

Understanding Permissions

Permissions are granular access controls organized by category. Each permission has:

• Name -- the permission identifier (e.g., question:create, exam:grade)
• Description -- what the permission allows
• Category -- grouping for organization (e.g., Questions, Exams, Users, Billing)

Viewing All Permissions

1. Go to "Admin" > "Roles & Permissions" > "Permissions" tab
2. Permissions are listed grouped by category
3. Each permission shows its name, description, and category

Common Permission Categories

Category	Example Permissions	Description
Questions	question:create, question:edit, question:delete	Question bank operations
Exams	exam:create, exam:publish, exam:grade	Exam lifecycle management
Users	user:view, user:create, user:edit	User management
Analytics	analytics:view, analytics:export	Reporting access
Billing	billing:view, billing:manage	Payment and subscription
AI	ai:generate, ai:configure	AI feature access
Admin	admin:settings, admin:audit	Administrative functions

Assigning Permissions to Roles

1. Go to "Admin" > "Roles & Permissions"
2. Click on a role to open its details
3. Navigate to the "Permissions" tab
4. Check or uncheck individual permissions
5. Click "Save Permissions"

Creating a New Permission

Super admins can define new permissions for custom features.

1. Go to "Admin" > "Roles & Permissions" > "Permissions" tab
2. Click "Create Permission"
3. Enter:
   • "Name" -- the permission key (e.g., reports:download)
   • "Description" -- what this permission controls
   • "Category" -- the grouping category
4. Click "Save"

Assigning Roles to Users

During User Creation

1. When creating a user via "Users" > "Add User"
2. Select the role from the "Role" dropdown
3. The user is assigned the role upon creation

Via Organization User Management

1. Go to "Organization" > "Users"
2. Find the user and click "Edit"
3. Change their role assignment
4. Click "Save"

Via Invite Links

When generating invite links, the role is pre-selected:

1. Go to "Users" > "Invite Links"
2. Select the role (Teacher or Student) when generating the link
3. Users who accept the invite are automatically assigned that role

Role Hierarchy and Access Control

The role hierarchy determines what each role can manage:

Super Admin
  |-- Can manage everything
  |
  +-- Org Owner
       |-- Can manage Org Admin, Teacher, Student within their org
       |
       +-- Org Admin
            |-- Can manage Teacher, Student within their org
            |-- Cannot manage other Org Admins or Org Owners
            |
            +-- Teacher
            |    |-- Can manage Student interactions (grades, exams)
            |    +-- Cannot manage other Teachers
            |
            +-- Student
            |    +-- Self-service only
            |
            +-- Parent
                 +-- Read-only access to linked students

Tip: Org admins cannot see or modify users with equal or higher roles. This prevents privilege escalation within an organization.

Middleware Enforcement

Testify enforces roles through multiple middleware layers:

• authenticateJWT -- verifies the user is logged in
• requireRole -- checks the user has the required role
• rbacMiddleware -- checks granular permissions
• tenantMiddleware -- ensures the user can only access their organization's data

These middleware layers are applied automatically to all API routes.

Troubleshooting

User Cannot Access a Feature

1. Check the user's assigned role under "Users" > click on the user
2. Verify the role has the required permission under "Roles & Permissions"
3. Ensure the feature is enabled for the organization (check "Feature Toggles")

Role Changes Not Taking Effect

• The user must log out and log back in for role changes to take effect
• JWT tokens carry role information and are valid for 15 minutes
• For immediate effect, the user can refresh their session

Cannot Delete a Built-In Role

Built-in roles are essential for system operation. If you need to restrict a built-in role, remove specific permissions instead of deleting the role.