Advanced Role-Based Access Control (RBAC) with custom roles, fine-grained permissions, and role templates.

1. Overview
2. System Roles
3. Custom Roles
4. Permission System
5. Role Templates
6. Best Practices
7. Examples

nself-chat provides enterprise-grade RBAC with:

• System Roles: Pre-defined roles (Owner, Admin, Moderator, Member, Guest)
• Custom Roles: Create unlimited custom roles with specific permissions
• Permission Groups: Organized permission sets by category
• Role Inheritance: Inherit permissions from base roles
• Role Templates: Quick-start templates for common scenarios
• Priority System: Resolve conflicts when users have multiple roles
• Time-Based Roles: Auto-expiring role assignments
• User Limits: Maximum users per role

Owner (100)
  └─ Administrator (80)
      └─ Moderator (60)
          └─ Member (40)
              └─ Guest (20)

• Level: 100 (Highest)
• Count: 1 (Transferable only)
• Permissions: All system permissions

Capabilities:

• Transfer ownership
• Configure system settings
• Manage all users and roles
• Access backup and restore
• Billing and subscription management

• Level: 80
• Permissions: All except ownership transfer

Capabilities:

• Manage users (create, edit, delete, ban)
• Manage channels (all operations)
• Configure integrations
• View audit logs and analytics
• Manage webhooks

• Level: 60
• Permissions: Content moderation and channel management

Capabilities:

• Create and manage channels
• Delete messages (any user)
• Mute/kick users
• View and resolve reports
• Pin messages
• Invite users

• Level: 40 (Default)
• Permissions: Standard chat functionality

Capabilities:

• Send messages
• Create threads
• Upload files
• Join channels
• Edit own messages
• React to messages

• Level: 20
• Permissions: Read-only access

Capabilities:

• View channels (invited only)
• React to messages
• Download files
• View user profiles

Navigate to Admin Dashboard → Users → Role Management

Name: Content Manager
Slug: content-manager
Description: Manages content across all channels
Color: #8B5CF6
Priority: 55
Base Role: moderator (optional)

Choose from 50+ granular permissions organized into categories:

• Channels: create, delete, update, archive, permissions
• Messages: send, edit, delete, pin, schedule
• Files: upload, download, delete
• Users: invite, ban, mute, assign roles
• Moderation: reports, warnings, slow mode
• Admin: dashboard, settings, integrations

Maximum Users: 10
Auto-Expire: 90 days
Default Role: false

Custom roles can inherit from:

1. Base Role: Inherit all permissions from a system role
2. Other Custom Roles: Inherit from multiple custom roles
3. Explicit Permissions: Add additional specific permissions

Example:

{
  name: "Community Manager",
  baseRole: "moderator",
  inheritedRoles: ["content-manager"],
  permissions: ["admin:analytics", "admin:webhooks"]
}

Effective Permissions = Base Role + Inherited Roles + Explicit Permissions

When a user has multiple roles:

1. Collect all permissions from all assigned roles
2. Remove duplicates (set union)
3. Apply priority for conflicting settings
4. Check expiration of time-based roles

Pre-configured templates for common scenarios:

Category: Management Base Role: Moderator Permissions: 15 Recommended: Yes

Ideal for community engagement leaders who manage channels and moderate content.

Key Permissions:

• Create/update channels
• Delete any message
• Invite users
• View/resolve reports

Category: Moderation Base Role: Moderator Permissions: 12 Recommended: Yes

Focused on content safety and moderation.

Key Permissions:

• Delete/edit any message
• Mute/kick users
• View reports
• Manage slow mode

Category: Support Base Role: Member Permissions: 8 Recommended: Yes

Customer support with read access to user information.

Key Permissions:

• View user profiles
• View user activity
• Send messages
• Access support channels

Category: Developer Base Role: Member Permissions: 6 Recommended: No

API and integration management.

Key Permissions:

• Manage webhooks
• Manage integrations
• View analytics

Category: Management Base Role: Member Permissions: 5 Recommended: No

Analytics and reporting access.

Key Permissions:

• View analytics
• View audit logs
• View user activity

Category: Management Base Role: Member Permissions: 10 Recommended: No

Manage specific channels without full moderation.

Key Permissions:

• Create/update/delete channels
• Manage channel permissions
• Pin messages

• Start with minimum permissions
• Add permissions as needed
• Regular permission audits

Use clear, descriptive names:

✅ Good: "Community Manager", "Content Moderator" ❌ Bad: "Role1", "SuperUser"

Document each custom role's purpose:

Name: Content Manager
Description: |
  Manages content creation and moderation across all
  public channels. Responsible for community engagement
  and content quality.
Responsibilities:
  - Review flagged content
  - Moderate discussions
  - Engage with community
  - Create announcements

• Monthly: Review role assignments
• Quarterly: Audit permissions
• Annually: Review custom roles

Test new roles in a staging environment:

1. Create role with limited permissions
2. Test with test user account
3. Verify expected behavior
4. Adjust permissions
5. Deploy to production

Separate concerns into multiple roles:

Instead of one "Power User" role:

• Create "Content Manager" for content
• Create "Community Manager" for engagement
• Create "Support Agent" for customer service

Create a role for marketing team with limited permissions:

{
  name: "Marketing Team",
  slug: "marketing-team",
  description: "Marketing team members with announcement privileges",
  color: "#F59E0B",
  priority: 45,
  baseRole: "member",
  permissions: [
    "channel:create",
    "message:send",
    "message:schedule",
    "message:pin",
    "file:upload"
  ],
  maxUsers: 5
}

Create a time-limited moderator role:

{
  name: "Event Moderator",
  slug: "event-moderator",
  description: "Temporary moderation for special events",
  color: "#8B5CF6",
  priority: 65,
  baseRole: "moderator",
  expiresAfter: 7, // Auto-expire after 7 days
  permissions: [
    "message:delete_any",
    "user:mute",
    "user:kick",
    "channel:update"
  ]
}

Admin with view-only permissions for compliance:

{
  name: "Compliance Officer",
  slug: "compliance-officer",
  description: "Read-only admin access for compliance review",
  color: "#3B82F6",
  priority: 75,
  permissions: [
    "admin:dashboard",
    "admin:audit_log",
    "admin:analytics",
    "user:view_activity",
    // No write/delete permissions
  ]
}

Create a role that inherits from multiple sources:

{
  name: "Senior Community Manager",
  slug: "senior-community-manager",
  description: "Senior role with combined permissions",
  color: "#10B981",
  priority: 70,
  baseRole: "moderator",
  inheritedRoles: [
    "community-manager",
    "content-moderator"
  ],
  permissions: [
    "admin:analytics",
    "admin:webhooks"
  ]
}

# Create custom role
mutation CreateRole {
  createRole(
    input: {
      name: "Content Manager"
      slug: "content-manager"
      baseRole: MODERATOR
      permissions: ["channel:create", "message:delete_any"]
      priority: 55
    }
  ) {
    id
    name
    permissions
  }
}

# Assign role to user
mutation AssignRole {
  assignRole(input: { userId: "user-123", roleId: "role-456", expiresAt: "2026-12-31T23:59:59Z" }) {
    id
    userId
    roleId
    expiresAt
  }
}

# Check user permission
query CheckPermission {
  userHasPermission(userId: "user-123", permission: "message:delete_any")
}

# Create role
POST /api/admin/roles
{
  "name": "Content Manager",
  "permissions": ["channel:create"]
}

# Assign role
POST /api/admin/users/{userId}/roles
{
  "roleId": "role-456"
}

# Get user permissions
GET /api/users/{userId}/permissions

1. Audit Current Usage

   SELECT role, COUNT(*) as user_count
   FROM users
   GROUP BY role;

2. Create Equivalent Custom Roles

   • Map system roles to custom roles
   • Add organization-specific permissions

3. Migrate Users

   • Assign custom roles
   • Maintain existing permissions

4. Deprecate Fixed Roles

   • Monitor usage
   • Remove when safe

Last Updated: January 2026 Version: 1.0.0