Skip to main content
Dispatcharr uses a role-based user system with three distinct permission levels. Configure user accounts, API access, and channel profile assignments.

​
User Levels

Dispatcharr defines three user levels with different capabilities:

Streamer

Level 0 - Streaming-only access

Standard User

Level 1 - Standard features

Admin

Level 10 - Full system access

​
User Model

Dispatcharr extends Django’s AbstractUser with custom fields:

​
Core Fields

Inherited from Django’s AbstractUser:
​
username
string
required
Unique username for authentication
​
email
email
User email address
​
password
string
required
Hashed password (managed by Django auth system)
​
first_name
string
User’s first name
​
last_name
string
User’s last name
​
is_active
boolean
default:true
Whether user account is active. Inactive users cannot log in.
​
is_staff
boolean
default:false
Django admin panel access
​
is_superuser
boolean
default:false
Full Django permissions (bypasses all checks)

​
Dispatcharr Custom Fields

​
user_level
integer
required
Permission level controlling access to features:
ValueLevelDescription
0StreamerStreaming-only access, no configuration
1StandardRegular user with standard features
10AdminFull administrative access
​
api_key
string
Optional API key for programmatic access. Used for:
  • M3U playlist downloads
  • EPG XML access
  • API authentication
Generated automatically or set manually.
​
channel_profiles
many-to-many
Associated channel profiles. Controls which channels user can access.References: dispatcharr_channels.ChannelProfile
​
avatar_config
json
Avatar configuration data:
{
  "type": "gravatar",
  "url": "https://gravatar.com/...",
  "initials": "JD",
  "color": "#3498db"
}
​
custom_properties
json
Extensible field for custom user metadata:
  • Preferences
  • UI settings
  • Integration tokens
  • Custom attributes

​
Creating Users

1

Navigate to User Management

Go to Settings > Users in the admin panel
2

Add New User

Click Add User and enter required fields
3

Set User Level

Choose appropriate permission level:
  • Streamer (0) - Viewing only
  • Standard User (1) - Normal operations
  • Admin (10) - Full control
4

Assign Channel Profiles

Select which channel profiles this user can access (optional)
5

Generate API Key

Create API key if programmatic access is needed (optional)

​
User Level Permissions

​
Streamer (Level 0)

Read-only streaming access:Allowed:
  • Watch assigned channels
  • View EPG data
  • Access personal playlists
Denied:
  • Modify any settings
  • Access admin panel
  • Create/edit channels
  • Configure sources

​
Standard User (Level 1)

Regular user features:Allowed:
  • All Streamer permissions
  • Manage personal favorites
  • Create custom playlists
  • Schedule recordings (if enabled)
  • View system status
Denied:
  • System configuration
  • User management
  • M3U/EPG source management
  • Global settings

​
Admin (Level 10)

Full system access:Allowed:
  • All Standard User permissions
  • Configure M3U sources
  • Configure EPG sources
  • Manage stream profiles
  • User management
  • System settings
  • Access all channels
  • View logs and diagnostics

​
Superuser Creation

When creating superusers via Django management commands, the custom manager automatically sets user_level: 
python manage.py createsuperuser
The CustomUserManager overrides the default behavior: 
def create_superuser(self, username, email=None, password=None, **extra_fields):
    extra_fields.setdefault('user_level', 10)  # Auto-set to Admin
    return super().create_superuser(username, email, password, **extra_fields)
All superusers are automatically assigned Admin level (10) permissions.

​
API Key Authentication

API keys enable programmatic access to Dispatcharr resources:

​
Generating API Keys

# Automatically generated or manually set
user.api_key = "dispatcharr_abc123xyz456..."
user.save()

​
Using API Keys

# M3U Playlist Access
curl -H "X-API-Key: dispatcharr_abc123xyz456" \
  https://dispatcharr.local/api/playlist.m3u

# EPG XML Access  
curl -H "X-API-Key: dispatcharr_abc123xyz456" \
  https://dispatcharr.local/api/epg.xml
API keys provide full account access. Keep them secure and rotate regularly.

​
Channel Profile Assignment

Control channel access per user via Many-to-Many relationship: 
# Assign channel profiles to user
user.channel_profiles.add(profile1, profile2)

# Get user's accessible channels
profiles = user.channel_profiles.all()

# Check if user has access to specific profile
has_access = user.channel_profiles.filter(id=profile_id).exists()
Admin users (level 10) typically have access to all channel profiles regardless of explicit assignments.

​
Groups and Permissions

Dispatcharr supports Django’s built-in groups and permissions system:

​
Group Management

# Get user's groups
groups = user.get_groups()

# Add user to group
from django.contrib.auth.models import Group
group = Group.objects.get(name="Premium Users")
user.groups.add(group)

​
Permission Management

# Get all user permissions (direct + group-based)
permissions = user.get_permissions()

# Check specific permission
if user.has_perm('channels.add_stream'):
    # User can add streams
    pass
The get_permissions() method combines:
  • Direct user permissions (user.user_permissions)
  • Group permissions (Permission.objects.filter(group__user=user))

​
Custom Properties

Store arbitrary user data in the custom_properties JSON field: 
{
  "theme": "dark",
  "language": "en",
  "default_quality": "1080p",
  "autoplay": true,
  "notifications_enabled": false
}

​
Avatar Configuration

Configure user avatars via avatar_config JSON field: 
{
  "type": "gravatar",
  "email": "user@example.com",
  "url": "https://gravatar.com/avatar/abc123",
  "fallback": {
    "type": "initials",
    "initials": "JD",
    "background": "#3498db",
    "color": "#ffffff"
  }
}
Supported avatar types:
  • gravatar - Gravatar service
  • initials - Generated from name
  • upload - Uploaded image
  • url - External image URL

​
Example User Configurations

{
  "username": "viewer123",
  "email": "viewer@example.com",
  "user_level": 0,
  "is_active": true,
  "channel_profiles": [1, 2, 3],
  "custom_properties": {
    "max_concurrent_streams": 2,
    "allowed_ips": ["192.168.1.0/24"]
  }
}

​
Best Practices

  • Use Streamer (0) for view-only accounts (family members, guests)
  • Use Standard (1) for regular users who need DVR/favorites
  • Use Admin (10) sparingly - only for trusted administrators
  • Don’t grant unnecessary permissions
  • Generate strong, random API keys
  • Rotate keys periodically
  • Use different keys for different integrations
  • Revoke keys immediately if compromised
  • Don’t share keys in public repositories
  • Create profiles based on content categories
  • Assign profiles based on user tier/subscription
  • Use profiles to enforce parental controls
  • Audit profile assignments regularly
  • Keep JSON structure consistent across users
  • Document custom property schema
  • Validate data before saving
  • Use for application-specific data only
  • Don’t store sensitive data unencrypted

​
Security Considerations

Password Security
  • Django automatically hashes passwords using PBKDF2
  • Never store plain-text passwords
  • Enforce strong password requirements
  • Enable two-factor authentication if available
API Key Protection
  • API keys are indexed in the database for fast lookups
  • Treat API keys like passwords
  • Use HTTPS to prevent interception
  • Implement rate limiting on API endpoints
Superuser Access
  • Superusers bypass all permission checks
  • Use sparingly and only for system administration
  • Monitor superuser activity in logs
  • Disable unused superuser accounts