What are User Roles?

User roles in CampusMindAI define what actions a user can perform and what resources they can access. The platform uses a role-based access control (RBAC) system to ensure users have appropriate permissions for their responsibilities.

Why Roles Matter

• Security: Limit access to sensitive operations and data

• Organization: Clearly define responsibilities and capabilities

• Compliance: Meet institutional policies for access control

• Workflow: Enable appropriate actions based on user function

Role Types

CampusMindAI has three primary role levels:

Student (Role ID: 1)

Primary Function: Learning and interaction with educational content

Permissions:

• Access assigned Virtual Teaching Assistants (VTAs)

• Interact with course-specific AI agents

• View course materials and announcements

• Submit assignments through VTA

• Access personal conversation history

• Use agents shared with student groups

Limitations:

• Cannot create or modify VTAs

• Cannot invite other users

• Cannot access administrative functions

• Cannot view other students' data

Instructor (Role ID: 2)

Primary Function: Course management and content creation

Permissions:

• All Student permissions, plus:

• Create and configure Virtual Teaching Assistants

• Manage course content and materials

• View student interactions with VTAs

• Create custom AI agents for courses

• Manage instructor-level groups

• Configure VTA settings and prompts

• Access course analytics and reports

• Share agents with student groups

Limitations:

• Cannot manage users outside their courses

• Cannot access tenant-wide settings

• Cannot delete other instructors' content

• Limited to course-level administration

Administrator (Role ID: 3)

Primary Function: Platform administration and user management

Permissions:

• All Instructor permissions, plus:

• Invite and manage users

• Create and manage groups

• Assign users to groups

• Configure tenant settings

• Access all VTAs and agents

• Manage global resources

• View system-wide analytics

• Configure integrations (Canvas, Blackboard)

• Manage API access

Limitations:

• Bound by tenant-level restrictions

• Cannot access other tenants' data

Role Assignment

During Invitation

Roles are assigned when inviting users to the platform:

{
  "email_address": "user@example.com",
  "access_token": "azure-ad-token",
  "user_role": 2
}

Role IDs

Permission Matrix

Role-Based Access Control

Group-Based Permissions

Users can be assigned to groups that provide additional access:

{
  "user_email": "student@example.com",
  "user_role": 1,
  "user_groups": ["CS101_Fall2024", "Engineering_Students"]
}

Groups can grant access to:

• Specific VTAs

• Shared agents

• Course resources

• Collaborative workspaces

Resource Ownership

Users can own resources based on their role:

Instructors own:

• VTAs they create

• Agents they build

• Course groups they manage

Administrators own:

• Global groups

• Tenant-wide configurations

• System integrations

Best Practices

Role Assignment Strategy

Start Conservative:

• Assign minimum required role initially

• Promote users as needs grow

• Review roles quarterly

Use Groups for Access:

• Grant resource access via groups, not individual permissions

• Create role-specific groups (e.g., "VTA_Admins", "Course_Instructors")

• Use groups for temporary access needs

Document Decisions:

• Maintain records of role changes

• Document reasons for elevated privileges

• Track role distribution across tenant

Security Recommendations

Principle of Least Privilege:

Student → Instructor → Administrator

Only promote when specific need is demonstrated.

Regular Audits:

• Review admin accounts monthly

• Verify instructor assignments align with actual courses

• Remove inactive accounts promptly

Separation of Duties:

• Don't assign admin role to regular instructors

• Use separate accounts for admin vs. instructional work

• Rotate admin responsibilities

Common Scenarios

New Faculty Member

Initial Role: Instructor (2)

Access Pattern:

1. Create VTAs for their courses

2. Manage student groups within courses

3. Access course analytics

Upgrade Path: Only promote to Admin if managing platform

Teaching Assistant

Initial Role: Instructor (2) or Student (1)

Decision Factors:

• Will they create VTAs? → Instructor

• Only helping with existing VTA? → Student with group access

Department Administrator

Initial Role: Administrator (3)

Responsibilities:

• Manage department users

• Oversee all department VTAs

• Configure department-wide settings

Guest Lecturer

Initial Role: Student (1) with group access

Access Pattern:

• Temporary access to specific VTA

• No content creation needs

• Time-limited access via group membership

Role Verification

Checking User Role

List users to see current roles:

curl -X POST "https://<baseURL>/api/v1/list_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 10}'

Response includes user_role:

{
  "user_email": "user@example.com",
  "user_role": 2
}

Permission Denied Errors

When users attempt unauthorized actions:

403 Forbidden: User's role lacks required permissions

Solutions:

• Verify user has correct role for the operation

• Check if operation requires group membership

• Confirm user owns the resource (for edit/delete)

Role Change Process

Promoting Users

Currently, role changes require:

1. Delete existing user account

2. Re-invite with new role

Important: This process may reset user data and preferences.

Future Enhancement

Role update endpoint (planned):

{
  "email_address": "user@example.com",
  "new_role": 3
}

Integration with Groups

Role + Group Model

Roles define base permissions, groups grant resource access:

Role: Student (base permissions)
  + Group: "Advanced_AI_Course" (access to specific VTA)
  + Group: "Research_Team" (access to research agents)

Group Roles

Groups can have associated role requirements:

Compliance and Auditing

Required Information

Maintain records of:

• User role assignments

• Role change history

• Access grant/revoke events

• Permission usage patterns

Audit Questions

Monthly Review:

• Who has admin access?

• Are instructor roles current with teaching assignments?

• Are there inactive accounts with elevated privileges?

Quarterly Review:

• Role distribution across tenant

• Access patterns vs. assigned roles

• Permission escalation requests

Compliance Reports

Generate role distribution reports:

# List all users and filter by role
curl -X POST "https://<baseURL>/api/v1/list_users/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 1000}'

Analyze user_role field distribution in results.