Skip to main content

Roles & Permissions

Lumio uses role-based access control (RBAC) to decide exactly what every team member can see and do inside your account. Roles are account-scoped: the same user can be a Moderator on your channel and an Owner on a friend's channel, and Lumio tracks that separately.

Who needs this guide?

  • Account owners setting up a team for the first time.
  • Administrators who need to create custom roles (for example, an "Editor" that can manage overlays but not chat).
  • Members who want to understand why a page or button is hidden for them.
  • Popout-token users configuring OBS browser-source docks with the right permissions.

Where to Find It​

  • Roles live under Dashboard → Roles (/dashboard/roles). You need roles:read to see the page and roles:edit / roles:delete to modify roles.
  • Members live under Dashboard → Members (/dashboard/members). You need members:read to see the list and members:edit to change someone's role.
  • Your own permissions are reflected everywhere — buttons, nav items, and entire pages simply disappear when you lack a permission, and protected pages show a "No Access" state with the message "Contact the account owner to get access."

Quick Start​

  1. The account creator is always the Owner — they start with every permission.
  2. Three other default roles exist for every new account: Administrator, Moderator, Viewer.
  3. To bring someone onto your team:
    • Open Dashboard → Members, click Invite.
    • Choose a method: Invite Link, Invite Token, or Invite Person (search by username/email/platform).
    • Pick a role (the Owner role cannot be assigned this way — it's reserved for the account creator).
    • Configure validity (1 hour, 24 hours, 7 days, 30 days, or Never) and max uses.
    • Share the link or token.
  4. If the four default roles don't fit, create a custom role under Dashboard → Roles → Create Role and pick exactly the permissions it needs.

How It Works​

Every action in Lumio — sending a chat message, saving an overlay, creating an invite — is guarded by a permission string in the form resource:action (for example chat:ban, overlays:edit). Wildcards like * or chat:* are not supported; permissions are always granular.

When a user performs an action, Lumio looks up the roles assigned to them on the current account, unions their permissions, and checks whether the required string is present.

  • The backend enforces permissions on every GraphQL resolver and REST handler, so switching protocols can't bypass a guard.
  • The frontend uses the same permission list to hide nav items, dim disabled buttons, and render graceful "No Access" pages instead of raw 403 errors.
  • Permissions are cached in Redis per user + account for performance. The cache is automatically invalidated whenever a role's permissions change, a member is added/removed, or a role is reassigned, so changes take effect within seconds.

Role anatomy​

Every role has:

FieldPurpose
nameHuman-readable label shown in the UI (e.g. "Moderator", "Content Editor").
slugMachine identifier auto-generated from the name (e.g. content-editor). Used for translations and API calls.
descriptionFree-text hint shown in the role list.
colorHex color used in the member list badge.
is_systemIf true, the role is protected: it can't be deleted and, for Owner, can't be edited.
permissionsThe list of resource:action strings granted by this role.

Default Roles​

Lumio seeds four roles into every new account. All slugs are stable and match those checked by the backend.

Owner (owner)​

  • is_system: true — cannot be deleted and is the only role that cannot be revoked from the account creator.
  • Holds every account permission including account:delete (dissolve the account) and plan:edit (change billing).
  • Automatically assigned to whoever created the account; ownership can be transferred via the settings page, but the role itself always exists.

Administrator (administrator)​

  • Same broad access as Owner, minus account:delete and plan:edit.
  • Can manage team, overlays, chat, automations, connections, etc. — essentially everything a co-streamer or production lead needs.
  • Can be deleted or edited (it is not a system role), but removing it usually isn't a good idea.

Moderator (moderator)​

  • Built for chat mods: chat:read, chat:write, chat:userinfo, chat:delete, chat:ban, chat:timeout, chat:notes, chat:raid, chat:poll, chat:prediction.
  • Read access to events, overlays, connections, uploads, rewards, bot-modules, bot-commands, bot-connections.
  • Spotify: read + playback + queue + playlist + device (no worker start/stop).
  • Automations: read + execute + history (cannot create or edit).
  • Members/roles: read-only (members:read, roles:read) — mods can see the team but not change it.
  • Sessions: can view and revoke their own active sessions.

Viewer (viewer)​

  • Read-only dashboard. Useful for a silent observer (a manager, an analytics seat, a backup account).
  • Has only events:read, events:userinfo, overlays:read, bot-commands:read, and session view/revoke.
  • Cannot chat, cannot touch automations, cannot see members or settings.

Custom Roles​

If the defaults don't fit — the most common case is "I want a role that can do X but not Y" — create a custom role.

  1. Open Dashboard → Roles, click Create Role.
  2. Step 1 — Role Details: enter a name, an optional description ("What can this role do?"), and pick a color. The slug is auto-derived.
  3. Step 2 — Permissions: check exactly the permissions you want. They are grouped by category (Events, Overlays, Spotify, Chat, …). The UI shows a running count at the bottom: "N permissions selected".
  4. Step 3 — Summary: review and click Create Role.

Editing works the same way — click the role in the list and the three-step wizard reopens with the current values. The Owner role shows as System and cannot be edited or deleted.

To assign a custom role: go to Dashboard → Members, find the member, and change their role from the Role column. You need members:edit to do this.

Permission Categories​

Permissions are grouped into categories that double as UI section headers in the role editor. Below are the categories and the resource:action strings inside each.

Granular pattern​

Almost every category follows the same shape:

  • resource:read — see the data.
  • resource:create — make new entries.
  • resource:edit — modify existing entries.
  • resource:delete — remove entries.

Two historical exceptions use :write instead of granular create/edit/delete:

  • chat:write — permission to send chat messages. (Deleting chat messages is separate: chat:delete.)
  • automations:write — covers create + edit + delete of automations as a single bundle. It exists because automation nodes depend on each other and splitting create/edit/delete introduced more friction than value.

Everywhere else, stick to the granular triple.

Events​

  • events:read — view the events feed and history.
  • events:create — emit test events.
  • events:delete — clear/remove events.
  • events:userinfo — open the user card from an event row.

Overlays​

  • overlays:read, overlays:create, overlays:edit, overlays:delete.

Spotify​

  • spotify:read — now playing, queue, devices, playlists, search.
  • spotify:playback — play / pause / skip / volume / shuffle / repeat.
  • spotify:queue — add tracks to the queue.
  • spotify:playlist — create / rename / delete playlists, manage tracks.
  • spotify:device — transfer playback between devices.
  • spotify:worker — start / stop the manual Spotify connect worker.

Chat​

  • chat:read, chat:write, chat:userinfo, chat:delete, chat:ban, chat:timeout, chat:notes, chat:raid, chat:poll, chat:prediction.
  • chat:userinfo also controls whether the \{\{username\}\}, \{\{displayName\}\}, \{\{avatarUrl\}\}, and \{\{userId\}\} automation template variables resolve (see Automation Templates).

Connections​

  • connections:read, connections:create, connections:edit, connections:delete — for Twitch/YouTube/Kick/Trovo channel connections, Discord, Spotify, StreamElements, etc.

Settings​

  • settings:read, settings:edit.

Members​

  • members:read — see the members and invites tabs.
  • members:create — create invite links / tokens / direct invites, search users.
  • members:edit — change someone's role.
  • members:delete — remove a member or revoke an invite.

Roles​

  • roles:read, roles:edit, roles:delete.

Uploads​

  • uploads:read, uploads:create, uploads:delete. Plan limits apply on top: Free = 5 MB per file / 100 MB total, Pro = 25 MB / 2 GB, Enterprise = 100 MB / 10 GB.

Rewards​

  • rewards:read, rewards:create, rewards:edit, rewards:delete — channel-point rewards and their handlers.

Tokens​

  • tokens:read, tokens:create, tokens:edit, tokens:delete — popout tokens and user API keys.

Automations​

  • automations:read, automations:write (bundled create+edit+delete), automations:execute, automations:history.

Account & Plan​

  • account:read, account:edit, account:delete (dissolve the whole account — Owner only by default).
  • plan:read, plan:edit (subscription / billing — Owner only by default).

Sessions​

  • sessions:read, sessions:delete — view and revoke active browser sessions.

OBS​

  • obs:read, obs:edit, obs:delete — the OBS WebSocket remote-control configuration.
  • copyright:read, copyright:edit, copyright:delete — the copyright review lists.
  • copyright:vote, copyright:report, copyright:recommend — viewer-style actions (moderators get these but not edit/delete).

Bot Modules / Bot Commands / Bot Connections / SE Tokens​

  • bot-modules:read, bot-modules:edit — link protection, spam, word filter, timed messages.
  • bot-commands:read, bot-commands:create, bot-commands:edit, bot-commands:delete.
  • bot-connections:read, bot-connections:create, bot-connections:delete — custom bot identities.
  • se-tokens:read, se-tokens:create, se-tokens:delete — StreamElements tip-jar tokens.

Concrete Recipes​

"A mod who can ban but not touch overlays"​

The default Moderator already does this — they have chat:ban + chat:timeout + chat:delete, and only overlays:read. If you want to also block overlay viewing, duplicate the Moderator role and drop overlays:read.

"A content editor who designs overlays but should never moderate chat"​

Create Content Editor with:

  • overlays:read, overlays:create, overlays:edit, overlays:delete
  • uploads:read, uploads:create, uploads:delete
  • rewards:read, rewards:edit
  • events:read, events:userinfo
  • settings:read (to see OBS URLs)
  • tokens:read, tokens:create (so they can create popout tokens for preview docks)

Leave chat, automations, connections, members, roles untouched.

"A stats-only seat for an agency / manager"​

Clone Viewer and add nothing, or add chat:read + chat:userinfo if they need to read chat for context. Do not grant chat:write.

"A co-host who can run the whole stream except billing"​

That's exactly Administrator. Assign it as-is.

"A VA who triggers automations but can't change them"​

Start from Moderator; ensure automations:read + automations:execute + automations:history are on; leave automations:write off. Optionally remove chat moderation if they shouldn't ban/timeout.

Popout Tokens​

When you create a popout token under Dashboard → Tokens, you choose a subset of permissions for that token. The token can never have more permissions than the creator's role — Lumio intersects the two lists on save.

A Moderator creating a popout token for OBS can therefore never produce a token with settings:edit or automations:write, even by editing the request manually.

Permissions Cheat-Sheet​

CapabilityPermission
Read chatchat:read
Send chat messageschat:write
Timeout userschat:timeout
Ban userschat:ban
Create overlaysoverlays:create
Edit overlaysoverlays:edit
Upload filesuploads:create
Connect Twitch/YouTube/etc.connections:create
Invite membersmembers:create
Change member rolesmembers:edit
Create custom rolesroles:edit
Create automationsautomations:write
Run automations manuallyautomations:execute
Create popout tokenstokens:create
Change plan / billingplan:edit
Dissolve accountaccount:delete

Tips & Best Practices​

  • Prefer custom roles over editing the defaults. If you change the Moderator role, every mod on the account changes with it. A custom "Chat Mod (no polls)" role keeps the default intact.
  • Start restrictive. It's easier to add permissions on request than to explain a security incident.
  • Name roles by function, not by person. "Content Editor" ages better than "Sarah".
  • Use the color field. Member badges use it — green-for-mods, blue-for-editors is much faster to scan than reading labels.
  • Invite tokens for manual distribution, invite links for DMs. Invite links include the role; the recipient clicks and lands on a "You have been invited" page. Tokens are paste-into-dashboard for people already signed in.
  • Sessions matter. If a collaborator's laptop is lost, revoke their sessions under Dashboard → Sessions before changing their role — otherwise their existing browser tab keeps the cached permissions until the next refresh.

Troubleshooting​

"Why can't I see the Music page?"​

Your role lacks spotify:read (and usually also spotify:playback). Ask the Owner to add the Spotify permissions — the entire Music nav item is hidden when spotify:read is missing.

"I see 'No Access — Contact the account owner to get access.'"​

You navigated to a URL (maybe from a bookmark) for a feature you don't have permission to use. The message is a deliberate friendly 403; check your role under Dashboard → Roles.

"I edited the role but the member still can't do the thing."​

The permission cache refreshes when the role is saved, but the member's browser may need a reload to pick up the new hidden/visible UI. Ask them to refresh. If it still fails, verify the permission string is really on the role (open the role, check the Permissions step).

"The Owner role is greyed out — I can't edit it."​

Correct. Owner is a system role (is_system: true). It always has every permission and cannot be modified or deleted. If you need a "near-Owner" role, edit or clone Administrator instead.

"I can't assign the Owner role when inviting."​

By design. The invite wizard hides Owner ("Owner role cannot be assigned"). Ownership transfers go through account settings, not invites.

"Can a member belong to multiple roles?"​

Currently no: each member has exactly one role per account. To give someone a superset of permissions, create a custom role combining the two.

"How do I give a popout token fewer permissions than my role?"​

Create the token under Dashboard → Tokens → New Token, and uncheck permissions you don't want on it. The list is pre-filled with your current permissions as the upper bound.