Permissions & Roles

Complete guide to configuring permissions and roles for Ticket System

Permissions Overview

Ticket System uses a comprehensive permission system that integrates with Discord's role system. This guide covers:

  • Understanding the permission hierarchy
  • Setting up roles and permissions
  • Configuring category-specific permissions
  • Managing staff access levels
  • Security best practices

Permission Hierarchy

System-Level Permissions

Permission Description Default Roles
System Administrator Full system access, can manage all settings Server Owner
Category Manager Can create and manage ticket categories Administrator
Staff Manager Can assign staff to categories Administrator
Analytics Viewer Can view analytics and reports Moderator

Ticket-Level Permissions

Permission Description Required Role
Create Tickets Can create new tickets Any user (configurable)
View Tickets Can see and access tickets Support Staff
Respond to Tickets Can send messages in tickets Support Staff
Close Tickets Can close tickets Senior Staff
Delete Tickets Can permanently delete tickets Administrator
Generate Transcripts Can create ticket transcripts Support Staff
Add Users Can add users to tickets Support Staff
Remove Users Can remove users from tickets Senior Staff

Setting Up Roles

1. Create Base Roles

In your Discord server, create the following roles in order of hierarchy:

@Administrator

  • Full system access
  • Can manage all categories
  • Can delete tickets
  • Can manage staff

@Senior Staff

  • Can close tickets
  • Can remove users
  • Can manage transcripts
  • Can view analytics

@Support Staff

  • Can view tickets
  • Can respond to tickets
  • Can add users
  • Can generate transcripts

@User

  • Can create tickets
  • Can view own tickets
  • Basic access only

2. Configure Role Colors

  • Administrator: Red (#FF0000)
  • Senior Staff: Orange (#FF8C00)
  • Support Staff: Blue (#5865F2)
  • User: Default (no color)

3. Set Role Permissions

# Discord Server Settings → Roles
# Configure each role with appropriate permissions

# Administrator Role
- Manage Server: ✅
- Manage Roles: ✅
- Manage Channels: ✅
- Kick Members: ✅
- Ban Members: ✅

# Senior Staff Role
- Manage Messages: ✅
- Manage Threads: ✅
- Send Messages: ✅
- Read Message History: ✅

# Support Staff Role
- Send Messages: ✅
- Read Message History: ✅
- Attach Files: ✅
- Embed Links: ✅

Category-Specific Permissions

1. Required Roles

Configure which roles are required to create tickets in each category:

  • None: Anyone can create tickets
  • Specific Role: Only users with that role can create tickets
  • Multiple Roles: Users need any of the specified roles

2. Blocked Roles

Configure which roles are blocked from creating tickets:

  • Banned Users: Prevent banned users from creating tickets
  • Muted Users: Prevent muted users from creating tickets
  • Custom Roles: Block specific roles as needed

3. Staff Roles

Configure which roles can manage tickets in each category:

  • Support Staff: Can view and respond to tickets
  • Senior Staff: Can close and manage tickets
  • Administrators: Full access to all tickets

4. Example Configuration

# General Support Category
requiredRoles: []
blockedRoles: ["@Banned", "@Muted"]
staffRoles: ["@Support Staff", "@Senior Staff", "@Administrator"]

# VIP Support Category
requiredRoles: ["@VIP", "@Premium"]
blockedRoles: ["@Banned"]
staffRoles: ["@Senior Staff", "@Administrator"]

# Bug Reports Category
requiredRoles: ["@Tester", "@Developer"]
blockedRoles: ["@Banned"]
staffRoles: ["@Developer", "@Administrator"]

Dashboard Permissions

1. Admin Panel Access

Feature Administrator Senior Staff Support Staff
View Dashboard ✅ ✅ ✅
Manage Categories ✅ ❌ ❌
View Analytics ✅ ✅ ❌
Manage Staff ✅ ❌ ❌
System Settings ✅ ❌ ❌

2. Analytics Permissions

  • Basic Analytics: Support Staff can view their own performance
  • Category Analytics: Senior Staff can view category performance
  • System Analytics: Administrators can view all analytics

Security Considerations

1. Principle of Least Privilege

  • Grant minimum permissions required for each role
  • Regularly audit role permissions
  • Remove unused permissions
  • Monitor permission changes

2. Role Hierarchy

  • Use Discord's role hierarchy to your advantage
  • Higher roles inherit permissions from lower roles
  • Be careful with role ordering
  • Test permissions thoroughly

3. Audit Logging

  • Enable Discord audit logs
  • Monitor permission changes
  • Track ticket access
  • Review logs regularly

4. Access Control

  • Limit admin access to trusted users only
  • Use temporary permissions when possible
  • Implement session timeouts
  • Require 2FA for admin accounts

Testing Permissions

1. Permission Test Checklist

Create Ticket Tests

  • ✅ Users with required roles can create tickets
  • ✅ Users without required roles cannot create tickets
  • ✅ Blocked users cannot create tickets
  • ✅ Error messages are clear and helpful

Ticket Management Tests

  • ✅ Support staff can view tickets
  • ✅ Support staff can respond to tickets
  • ✅ Senior staff can close tickets
  • ✅ Administrators can delete tickets

Dashboard Access Tests

  • ✅ Users can access appropriate dashboard sections
  • ✅ Users cannot access restricted sections
  • ✅ Analytics are filtered by permission level
  • ✅ Error messages are shown for unauthorized access

2. Automated Testing

# Run permission tests
npm run test:permissions

# Test specific scenarios
npm run test:permissions -- --category=general-support
npm run test:permissions -- --role=support-staff

Troubleshooting

Common Permission Issues

Users Can't Create Tickets

  • Check required roles configuration
  • Verify user has the required role
  • Check if user is blocked
  • Review category settings

Staff Can't Access Tickets

  • Verify staff role assignment
  • Check category staff configuration
  • Ensure role hierarchy is correct
  • Test with different staff members

Dashboard Access Issues

  • Check Discord OAuth2 permissions
  • Verify user has required server roles
  • Clear browser cache and cookies
  • Check authentication logs

Permission Inheritance

  • Check Discord role hierarchy
  • Verify role ordering in server settings
  • Test with different role combinations
  • Review permission inheritance logic

Debug Commands

# Check user permissions
/ticket permissions @username

# List category permissions
/ticket categories

# Test permission system
npm run debug:permissions -- --user=@username --category=general

Best Practices

1. Role Design

  • Use descriptive role names
  • Keep roles focused and specific
  • Document role purposes
  • Regularly review and clean up roles

2. Permission Management

  • Start with minimal permissions
  • Add permissions as needed
  • Document permission changes
  • Test permissions thoroughly

3. Security Monitoring

  • Monitor permission changes
  • Track access patterns
  • Review audit logs regularly
  • Set up alerts for suspicious activity

    • 4. User Training

    • Train staff on permission system
    • Provide clear documentation
    • Create permission guides
    • Regularly review and update training

    Next Steps

    After configuring permissions:

    1. Create Categories - Set up ticket categories with proper permissions
    2. Configure Auto-Close - Set up automatic ticket management
    3. Set Up Dashboard - Configure the web interface
    4. Configure Analytics - Set up reporting and monitoring