RBAC & Permissions

Lumio uses a role-based access control (RBAC) system with granular permissions. Every authenticated action is checked against the user's assigned role for the active account.

Default Roles

Every new account is created with four default roles:

Role	Slug	Color	is_system	is_default	Notes
Owner	owner	#f59e0b	true	true	All permissions. Cannot be edited or deleted.
Administrator	administrator	#ef4444	false	true	All permissions except account:delete and plan:edit.
Moderator	moderator	#22c55e	false	true	Chat moderation, event monitoring, read access.
Viewer	viewer	#6b7280	false	true	Read-only: events:read, overlays:read, events:userinfo.

Role Properties

Property	Type	Description
slug	string	Machine-readable identifier. Stable, lowercase, used in code checks. Never changes.
name	string	Human-readable display name. Editable on custom roles, translated for default roles.
is_system	bool	Cannot be edited or deleted. Only the Owner role.
is_default	bool	Cannot be deleted. All four default roles have this set.
color	string	Hex color for UI display (e.g., "#f59e0b").

Role Name Translation

Default role names are translated via the useTranslateRole() hook in apps/web/src/lib/translate-role.ts. The hook returns a (slug, name) => string function that checks if the slug matches a known default role and returns the localized name; custom roles fall back to their name field.

Translation keys live in apps/web/messages/{en,de}.json under "roles.labels":

{
  "roles": {
    "labels": {
      "owner": "Owner",
      "administrator": "Administrator",
      "moderator": "Moderator",
      "viewer": "Viewer"
    }
  }
}

Permission Format

All permissions follow the resource:action format. Examples:

• events:read, events:create, events:delete
• chat:ban, chat:timeout, chat:notes
• automations:execute, automations:history

Rules

1. Always granular. Every resource needs at minimum read plus granular create/edit/delete.
2. Domain-specific actions are added when CRUD is insufficient (e.g., automations:execute, chat:ban).
3. Never use wildcards. No resource:manage or resource:* for account-level permissions. The only wildcard is the global admin permission admin:*, which is restricted to system administrators.

Account Permissions

The tables below summarize the major account permission categories. The authoritative list of constants lives in crates/lo-auth/src/rbac.rs (under pub mod account {}) — treat that file as the source of truth; categories and counts may shift as features evolve.

Events

Permission	Label
events:read	Read Events
events:create	Create Events
events:delete	Delete Events
events:userinfo	Event User Info

Overlays

Permission	Label
overlays:read	Read Overlays
overlays:create	Create Overlays
overlays:edit	Edit Overlays
overlays:delete	Delete Overlays

Spotify (6)

Permission	Label	Owner	Admin	Mod	Viewer
spotify:read	Read Spotify	x	x	x
spotify:playback	Spotify Playback	x	x	x
spotify:queue	Spotify Queue	x	x	x
spotify:playlist	Spotify Playlists	x	x	x
spotify:device	Spotify Devices	x	x	x
spotify:worker	Spotify Worker	x	x

Chat (11)

Permission	Label	Owner	Admin	Mod	Viewer
chat:read	Read Chat	x	x	x
chat:write	Write Chat	x	x	x
chat:userinfo	Chat User Info	x	x	x
chat:delete	Delete Chat Messages	x	x	x
chat:ban	Ban Chat Users	x	x	x
chat:timeout	Timeout Chat Users	x	x	x
chat:notes	Chat User Notes	x	x	x
chat:raid	Cancel Raids	x	x	x
chat:poll	End Polls	x	x	x
chat:prediction	End Predictions	x	x	x
chat:refresh_user	Refresh User Profile	x	x	x

Connections

Permission	Label
connections:read	Read Connections
connections:create	Create Connections
connections:edit	Edit Connections
connections:delete	Delete Connections

Settings (2)

Permission	Label	Owner	Admin	Mod	Viewer
settings:read	Read Settings	x	x
settings:edit	Edit Settings	x	x

Members (4)

Permission	Label	Owner	Admin	Mod	Viewer
members:read	Read Members	x	x	x
members:create	Create Invites	x	x
members:edit	Edit Members	x	x
members:delete	Delete Members	x	x

Roles (3)

Permission	Label	Owner	Admin	Mod	Viewer
roles:read	Read Roles	x	x	x
roles:edit	Edit Roles	x	x
roles:delete	Delete Roles	x	x

Uploads

Permission	Label
uploads:read	Read Uploads
uploads:create	Create Uploads
uploads:delete	Delete Uploads

Rewards

Permission	Label
rewards:read	Read Rewards
rewards:create	Create Rewards
rewards:edit	Edit Rewards
rewards:delete	Delete Rewards

Tokens

Permission	Label
tokens:read	Read Tokens
tokens:create	Create Tokens
tokens:edit	Edit Tokens
tokens:delete	Delete Tokens

Automations (6)

Permission	Label	Owner	Admin	Mod	Viewer
automations:read	Read Automations	x	x	x
automations:create	Create Automations	x	x
automations:edit	Edit Automations	x	x
automations:delete	Delete Automations	x	x
automations:execute	Execute Automations	x	x	x
automations:history	Automation History	x	x	x

Account (3)

Permission	Label	Owner	Admin	Mod	Viewer
account:read	Read Account	x	x
account:edit	Edit Account	x	x
account:delete	Delete Account	x

Plan (2)

Permission	Label	Owner	Admin	Mod	Viewer
plan:read	Read Plan	x	x
plan:edit	Edit Plan	x

Login Assignments (3)

Controls access to login assignment management. Own assignments are always allowed for any authenticated user regardless of role — the permissions below only gate actions performed on behalf of other users.

Permission	Label	Owner	Admin	Mod	Viewer
login-assignments:read	Read Login Assignments	x	x
login-assignments:create	Create Login Assignments	x	x
login-assignments:delete	Delete Login Assignments	x	x

Ideas Hub (User-Scoped)

The Ideas Hub introduces a user-scoped permissions layer that is distinct from both account-scoped and admin-scoped permissions. User-scoped permissions are global (not tied to a specific account) and are assigned via the user_roles and user_role_permissions tables.

Enforcement uses auth.require_user_permission(). The moderation checks use has_moderate_permission(), which accepts BOTH user-scoped and admin-scoped grants.

User-scoped permissions:

Permission	Label
ideas:read	Read Ideas
ideas:create	Create Ideas
ideas:edit	Edit Own Ideas
ideas:delete	Delete Own Ideas
ideas:vote	Vote on Ideas
ideas:comment_read	Read Comments
ideas:comment_create	Create Comments
ideas:comment_edit	Edit Own Comments
ideas:comment_delete	Delete Own Comments

Admin-scoped moderation permissions:

Permission	Label
ideas:moderate_read	Read All Ideas (Admin)
ideas:moderate_status	Change Idea Status
ideas:moderate_edit	Edit Any Idea
ideas:moderate_delete	Delete Any Idea
ideas:moderate_comment	Delete Any Comment

Admin-scoped moderation permissions are enforced via auth.require_admin_permission() and live in crates/lo-auth/src/rbac.rs::global.

Admin-Scope Permissions

Admin-scope permissions gate the Lumio admin panel (/admin) and are entirely separate from account-scope permissions. They are stored in the admin_permissions column of CachedPermissions (not account_permissions) and enforced by require_admin_permission().

Two Modules, Two Contexts

The crates/lo-auth/src/rbac.rs file defines two modules:

• pub mod account {} — Account-scope permission constants (listed above)
• pub mod global {} — Admin-scope permission constants

Constants in global use the same resource:action format. The canonical list is exposed via:

lo_auth::rbac::all_admin_permissions() -> Vec<(&'static str, &'static str)>
// Returns (permission_string, category_label) pairs

This function is used by the permission picker UI and the REST/GraphQL permission validation.

Admin Roles

Admin roles are managed in the admin_roles / admin_role_permissions / user_admin_roles tables (migration 20260412000001). Unlike account roles, admin roles:

• Are global (not account-scoped)
• Have is_system: bool — system roles cannot be deleted
• Auto-receive admin:access (the dashboard entry gate) on creation
• Are CRUD-managed via adminRoles* GraphQL mutations and GET/POST/PATCH/DELETE /v1/admin/admin-roles

Shared Permissions

Some permission strings (e.g., copyright:read, obs:read, bot-modules:read) are declared in both pub mod account {} and pub mod global {} with identical string values. This is intentional — the same string gates different resources in different contexts:

• Account scope: enforced by auth.require_permission(account::COPYRIGHT_READ) in account route handlers
• Admin scope: enforced by auth.require_admin_permission(global::COPYRIGHT_READ) in admin route handlers

This follows the precedent set by bot-connections:*.

admin:access

admin:access is the single gate that controls dashboard access. Any user without this permission sees a "No Access" page. It is:

• Always present in the global module as admin::ACCESS
• Auto-injected into every admin role at creation time (both REST and GraphQL mutation)
• Never removed by the permission diff algorithm

admin:privacy-erase

GDPR-Art-17 erasure tooling. Today gates the YouTube member-badge erasure endpoint (DELETE /v1/admin/privacy/youtube/member/{id} plus eraseYoutubeMemberData GraphQL mutation) which clears cached YouTube member-channel records across all accounts. Reserved for the system_admin role; not auto-injected into any other admin role. The audit log records both a global and a per-account row for every erasure (event_type = "youtube_member_erasure").

Guard selection

When writing a GraphQL resolver, pick the right guard:

• AdminPermissionGuard::new("resource:action") — admin-scope operations (the permission lives in crates/lo-auth/src/rbac.rs::global). Only users with admin permissions can call these; account-scope role permissions do NOT grant access.
• PermissionGuard::new("resource:action") — account-scope operations (the permission lives in rbac.rs::account). System admins can also act (their admin role has the permission via is_system = true).
• AuthGuard — any-authenticated operations, no specific permission required.

Backend Enforcement

GraphQL: PermissionGuard and AdminPermissionGuard

GraphQL resolvers use one of two guards from crates/lo-graphql/src/guard.rs.

Account-scope resolvers use PermissionGuard:

#[graphql(guard = "lo_graphql::PermissionGuard::new(\"events:read\")")]
async fn events(&self, ctx: &Context<'_>) -> async_graphql::Result<Vec<Event>> {
    // ...
}

Admin-scope resolvers use AdminPermissionGuard:

#[graphql(guard = "lo_graphql::AdminPermissionGuard::new(\"users:edit\")")]
async fn admin_edit_user(&self, ctx: &Context<'_>) -> async_graphql::Result<AdminUser> {
    // ...
}

PermissionGuard checks AuthContext::has_permission(), which accepts both admin and account permissions (system admins pass both). AdminPermissionGuard delegates exclusively to auth.require_admin_permission(), which only inspects admin_permissions — account-scope role grants do NOT satisfy it.

REST: require_permission

Every Actix route handler uses require_permission() from crates/lo-auth/src/context.rs:

use lo_auth::rbac::account;

pub async fn list_events(auth: Auth, state: web::Data<AppState>) -> Result<HttpResponse, ApiError> {
    auth.require_permission(account::EVENTS_READ)
        .map_err(from_auth_error)?;
    // ...
}

This returns an AuthError::MissingPermission which maps to HTTP 403.

Permission Constants

All permission constants are defined in crates/lo-auth/src/rbac.rs inside pub mod account {}. Use the constants (not string literals) in REST handlers to prevent typos.

WebSocket: channel gate

The WebSocket layer (crates/lo-websocket/src/gate.rs) maps each account-scoped channel to a :read permission. The WsSession calls channel_gate_for(channel_type) on every subscribe and broadcast request, then runs the permission check against the same AuthContext the REST/GraphQL layers see:

// crates/lo-websocket/src/gate.rs
pub fn channel_gate_for(channel_type: &str) -> ChannelGate {
    match channel_type {
        "overlay"     => ChannelGate::Public,
        "events"      => ChannelGate::Permission("events:read"),
        "spotify"     => ChannelGate::Permission("spotify:read"),
        "chat"        => ChannelGate::Permission("chat:read"),
        "automations" => ChannelGate::Permission("automations:read"),
        _ => ChannelGate::Unknown,
    }
}

After RBAC, the same module also runs a feature-flag check via the FeatureGate trait (implemented by FeatureService in apps/api/src/websocket/mod.rs). Channels mapped in channel_feature_for reject subscribes for accounts whose plan/account-feature row has the flag off — currently only automations:* → feature:automation. Adding a new paid-tier channel: extend both functions in one edit.

A subscribe failure raises a typed error message back to the client: code: "UNAUTHORIZED" for missing permissions and code: "FEATURE_DISABLED" for disabled feature flags. Clients should surface both as user-facing "no access" / "upgrade plan" hints.

Important: when adding a new account-scoped WebSocket channel type, you MUST extend channel_gate_for in the same PR — the default match arm returns ChannelGate::Unknown which rejects the subscribe with UNAUTHORIZED for every caller, including Owners. Forgetting this step ships a broken channel that nobody can use.

Frontend Enforcement

PermissionProvider

The PermissionProvider React context (apps/web/src/contexts/permission-context.tsx) receives the user's permissions from the server layout and makes them available to all client components via hooks.

Gate Component

Declaratively renders children only when the user has the required permission:

<Gate permission="overlays:create">
  <Button>Create Overlay</Button>
</Gate>

PermissionErrorBoundary

Wraps entire page content to show a "No Access" fallback for users without the permission:

<PermissionErrorBoundary permission="spotify:read">
  <MusicPlayer />
</PermissionErrorBoundary>

Imperative Checks

For use in hooks or event handlers:

const canEdit = useHasPerm("overlays:edit");

See Frontend Permission System for the full API reference.

Redis Cache

Permissions are cached in Redis to avoid database lookups on every request.

CachedPermissions

The CachedPermissions struct in crates/lo-cache/src/client.rs stores permissions split by scope:

pub struct CachedPermissions {
    pub global: Vec<String>,   // Admin-level permissions
    pub account: Vec<String>,  // Account-level permissions
}

• Cache key: lumio:perms:{user_id}:{account_id}
• TTL: 300 seconds (5 minutes)
• Invalidation: RedisClient::invalidate_permissions() is called whenever a user's role assignment changes

Key Files

File	Purpose
crates/lo-auth/src/rbac.rs	Permission constants (account + global/admin) + all_admin_permissions()
crates/lo-auth/src/context.rs	AuthContext::has_permission() + require_permission() + require_admin_permission()
crates/lo-graphql/src/guard.rs	PermissionGuard (account-scope) + AdminPermissionGuard (admin-scope) for GraphQL resolvers
crates/lo-cache/src/client.rs	CachedPermissions + Redis cache/invalidation
apps/api/src/graphql/roles.rs	GraphQL available_permissions list (account scope)
apps/api/src/graphql/admin.rs	GraphQL adminRoles* queries and mutations (admin scope)
apps/api/src/routes/roles.rs	REST available_permissions list + validation
apps/api/src/routes/admin.rs	REST admin-roles + admin-permissions endpoints
apps/api/src/db/admin_roles.rs	DB helpers for admin role CRUD
apps/web/src/contexts/permission-context.tsx	PermissionProvider + usePermissions() + useHasPerm()
apps/web/src/components/gate.tsx	<Gate> declarative permission component
apps/web/src/components/permission-error-boundary.tsx	Page-level access denial
apps/web/src/lib/translate-role.ts	translateRole() hook for default role names