Yzbot's Permission System & Moderator and Admin Roles
This page explains how yzbot determines whether to let someone use a command or not. You can either have a specific permission/permissions, or possess a Moderator or Administrator role.
NEW: Permission Nodes!
You can now grant or deny access to commands on a per-user, per-role or server-wide basis. This is through a highly configurable permission node system. A permission node can have three states: allowed, neutralised or negated. In order to manage these permission nodes, you must use the ;setperms command.
The command is used with the following syntax: ;setperms <command> <server/role name/mention/user ID>.
You replace <command> with the name of the command whose permission node you want to manage.
IMPORTANT: If you want to allow the permission node, you must put a + before the command name. If you want to negate it, you must put a - before the command name. To neutralise (remove) the permission node, put nothing before the command name.
To set the permission node server-wide, type 'server' after the command name. If you want it to affect the members of a certain role, type the name of the role after the command name. Finally, if you just want to set the permission node for a specific member, then either mention them or provide their user ID.
Firstly, negating permission nodes:
If we try ;ping...
We can't! If we want to 'remove' or neutralise the negated permission node (allowing the user to use ;ping again), we do the following:
Finally, if we want to allow this user to use a command they otherwise would be unable to, we can allow a permission node like so:
Viewing Permission Nodes
If you need to know what permission nodes are set server-wide, for a user or a role, type ;permnodes. If you pass it no arguments, it will show the server-wide permission nodes by default. To view permission nodes for a specific role, type ;permnodes <role name>, replacing <role name> with the name of the role. Finally, if you want to view user-specific permission nodes type ;permnodes <user> and this time, you have to mention the user, you cannot provide an ID (this DOES NOT show you the accumulated permissions of a user, from roles or server-wide settings).
NOTES
If you want to manage permissions of a role called 'server'... you can't. You have to contact Support.
Changes take up to 15 seconds to take effect for performance reasons.
If a user has one role that is higher than another role, then the higher role's permission node will take effect. Permission nodes for roles are determined based on the role's position in the hierarchy.
Server-wide permission nodes are always overriden by role permission nodes, which are always overriden by user-specific permission nodes.
If you negate a permission, it always overrides permission levels and Discord permissions. If you allow a permission node, a permission level check is carried out first, and if that fails, the permission node acts as a failsafe to allow the user to use the command.
Using Permissions
Regardless of whether the moderator and administrator roles are configured or not, yzbot's commands have some permissions that will allow a user, by default, to use the command. For example, if someone has the Kick Members permission and wants to use the kick command, it doesn't matter whether or not they have the configured Server Moderator role (if one is), yzbot will still allow them to use the command.
Permission System
Yzbot has a permission system, which is divided into five levels. Each level inherits all permissions from the level below and gets some extra permissions:
Level 0 (User) - This is your average bot user or server member. They can do plenty of things, but they will not be able to use moderation or administration commands.
Level 1 (Server Moderator) - This permission level is intended for general server moderators. People with this permission level can kick, ban, mute, warn and much more. However, they cannot configure the bot's settings in the server. That job is for people at...
Level 2 (Server Admin) - These people get to moderate the server and configure the bot (it is mostly people at this permission level that this GitBook targets!)
Level 3 (Server Owner) - The server owner is automatically assigned to this permission level. At the moment, I have not found a use for this permission level, but I will in the future.
Level 4 (Yzbot Support Team Member) - This permission level is given to my bot's support staff so that they can easily diagnose issues without having to mess around with permissions. This level also grants them the ability to reply to contact requests.
Level 5 (Yzbot Developer) - Me! Obviously, as the developer, I get the highest permission level, granting me some extra spooky secret commands.
Managing Moderator and Admin Roles
Permission levels 1 and 2 are not assigned to anyone, or any role, by default. In order for people to have those permission levels, you must configure moderator and admin roles.
Moderator
In order to set up a moderator role, you need to type ;managepermroles mod <role name>, and replace <role name> with whatever role name that you want. Anyone with this role is now permission level 1 in yzbot's permission system. You can use the same command to change the Moderator role too.
If you no longer want members of that role to be server moderators, simply type ;managepermroles delete mod and it will delete the Moderator role setting.
Admin
Setting up the Admin role works exactly the same way. Just type ;managepermroles admin <role name> this time, replacing <role name> with the name of the role you want to have as the Admins. These people are now permission level 2 in yzbot's permission system. You can use the same command to edit the Admin role setting too.
In the same vein, if you no longer want the members of the role that you set as the Admin role to have Admin permissions with yzbot, simply type ;managepermroles delete admin and the Admin role setting will be removed.
Last updated
Was this helpful?