Roles & permissions

A role is a named set of permissions and display settings. Each user has a list of roles, and those roles decide what the user can do on the server and in each channel.

Permissions work in two layers:

• Server permissions such as manage_channels live on roles. They unlock administrative commands.
• Channel permissions live on channels. They list which roles can view, send, react, and so on in that channel.

Roles

{
  "cmd": "roles_list",
  "val": {
    "moderator": {
      "name": "moderator",
      "id": "0c8e4a52-6f1d-4b3a-9e27-5d4c3b2a1f09",
      "description": "Moderator role with elevated permissions.",
      "color": "#FFFF00",
      "hoisted": true,
      "permissions": ["manage_messages", "manage_threads"],
      "self_assignable": false,
      "position": 2
    }
  }
}

Roles are keyed by name. Each role also has an id, which role mentions use. position sets rank: a lower number means more authority, and 0 is the top.

A new server starts with four roles:

Role	Position	Permissions
owner	0	owner, administrator
admin	1	administrator
moderator	2	manage_messages, manage_threads, and some reserved names the server doesn’t check
user	3	create_invite

New members get the user role. The server adds a banned role name to a user’s list when they’re banned. See moderation.

Use roles_list to read roles and user_roles_get to read one user’s roles.

Names, colors, and order

A user’s roles is an ordered list of role names. The user’s name color and gradient come from the first role in that list that has a color or gradient set.

Tip

A role created without a color stores an empty value, and an empty value still counts as set. Put the role whose style should show at the front of the user’s list. Users can reorder their own roles with self_roles_reorder.

Roles are referenced by name, so renaming or deleting one leaves old references behind:

• Renaming a role doesn’t update members’ role lists or channel permission rules. They keep the old name, which no longer matches a role.
• Deleting a role leaves its name in members’ roles lists.

Update members and channel rules yourself after a rename or delete.

Server permissions

The server checks a named permission in this order:

1. A user with the owner role has every permission.
2. A user with any role that includes administrator has every permission.
3. Otherwise, one of the user’s roles must list the permission.

Permission	What it unlocks
manage_server	Server settings, stats, and maintenance, webhooks, plugins, listing and deleting any attachment. Also skips slow mode.
manage_channels	Creating, changing, moving, and deleting channels, and /slow.
manage_users	Bans, kicks, timeouts, severing, profile changes, and seeing hidden presence. Also reads the audit log.
manage_roles	Creating, changing, reordering, deleting, and assigning roles. Also skips paying for paid roles.
manage_emojis	Adding, changing, and deleting custom emoji and stickers.
manage_config	Reading and changing the server configuration.
manage_access	Access mode, whitelist, server password, and invite management. See access control.
create_invite	Creating invites.
review_applications	Reviewing membership applications.
review_reports	Listing and closing reports.
view_audit_log	Reading the audit log.
manage_threads	Locking and pinning threads, and changing or deleting anyone’s thread.
manage_messages	Setting a channel’s sticky message with /sticky.
mention_roles	Mentioning any role.

The handshake lists the main permission names in permissions. A role can also include is_mentionable. That isn’t a user permission. It lets anyone mention that role, except the user role.

Channel permissions

Each channel has a permissions object that maps an action to a list of role names:

{
  "view": ["user"],
  "send": ["admin", "moderator"],
  "react": ["user", "!muted"]
}

A user can perform an action if the rule allows one of their roles:

• A plain role name allows that role.
• !role denies that role. Denials win over grants.
• A list with no plain role names, including an empty list, allows everyone who isn’t denied.
• A user with the owner role passes every channel rule.

Caution

administrator doesn’t bypass channel rules. An administrator can see or post in a channel only if one of their roles is allowed there.

Missing actions use these defaults:

Action	Default roles	Controls
view	user	Seeing the channel and reading its messages.
send	user	Posting messages.
edit_own	user	Editing your own messages.
edit	owner	Editing other people’s messages.
delete_own	user	Deleting your own messages.
delete	owner, admin	Deleting other people’s messages.
react	user	Adding and removing reactions.
pin	owner, admin, moderator	Pinning messages and ending other people’s polls.
create_thread	user	Creating threads in a forum channel.

Threads use their parent forum’s rules. See manage the server for worked examples of channel rules.

Managing roles safely

The server stops managers from giving out more power than they have. For anyone except the owner, managing a role requires:

• manage_roles.
• The role isn’t owner, admin, or user. These are protected.
• The role’s position is lower than the manager’s highest role. A manager can’t manage roles at or above their own.
• The manager holds every permission the role grants, unless they’re an administrator.

These rules apply when creating, changing, deleting, assigning, and removing roles. user_roles_set checks each role being added or removed, and can’t remove anyone’s owner role. The protected roles can’t be deleted or made self-assignable.

Note

role_reorder needs only manage_roles. It doesn’t apply the position checks.

When roles change

• Creating, changing, deleting, or reordering a role broadcasts the change to everyone connected.
• Changing a user’s roles broadcasts user_roles_get with their new roles, color, and gradient.
• If the change alters which channels that user can view, the server sends them a fresh channels_get.
• The server re-checks who has manage_users, because that decides who can see hidden presence. See users and presence.

Self-assignable roles

A role with self_assignable: true can be added or removed by any member with self_role_add and self_role_remove. Use this for opt-in roles such as pronouns or notification groups. self_roles_list lists them.

A member can’t self-assign a role that grants a permission they don’t already have.

Paid roles

A self-assignable role with a price above zero must be bought before a member can add it. Payment goes through Rotur to the server owner.

1. The client reads the role’s price and the payee username from self_roles_list. An empty payee means purchases aren’t set up on this server.
2. The member pays the owner through Rotur for that role.
3. The client sends self_role_add with the Rotur payment ID in payment.

The server checks the owner’s Rotur earnings for that payment. The payment must come from the member’s account, be for this role’s ID, and cover the price. On success, the role goes to the front of the member’s list, so its style shows. The role ID is saved in the member’s purchased_roles, so they can remove and re-add it later without paying again. self_roles_list marks bought roles with owned: true.

Local accounts can’t buy roles. Members with manage_roles add paid roles without paying.

See also

• Role commands
• Role schema
• Manage the server