# Permissions (extended)

# Discord's permission system

Discord permissions are stored in a 53-bit integer and calculated using bitwise operations. If you want to dive deeper into what's happening behind the curtains, check the Wikipediaopen in new window and MDNopen in new window articles on the topic.

In discord.js, permission bit fields are represented as either the decimal value of said bit field or its referenced flags. Every position in a permissions bit field represents one of these flags and its state (either referenced 1 or not referenced 0).

Before we get into actually assigning permissions, let's quickly go over the method Discord uses to determine a guild member's final permissions:

1. Take all permissions for all roles the guild member has and add them up.
2. Apply all denies for the default role (@everyone).
3. Apply all allows for the default role (@everyone).
4. Apply all denies for all additional roles the guild member has at once.
5. Apply all allows for all additional roles the guild member has at once.
6. Apply all denies for the specific guild member if they exist.
7. Apply all allows for the specific guild member if they exist.

Due to this system, you cannot deny base permissions. If you grant SendMessages to @everyone and don't grant it for a muted members role, muted members will still be able to send messages unless you specify channel-based overwrites.

All additional roles allow overwrites are applied after all additional roles denies! If any of a member's roles have an overwrite to allow a permission explicitly, the member can execute the associated actions in this channel regardless of the role hierarchy.

Placing an overwrite to allow SendMessages on a role will result in members with this role not being mutable via role assignment in this channel.

# Elevated permissions

If the guild owner enables the server's two-factor authentication option, everyone executing a specific subset of actions will need to have 2FA enabled on their account. As bots do not have 2FA themselves, you, as the application owner, will need to enable it on your account for your bot to work on those servers. Check out Discord's help articleopen in new window if you need assistance with this.

The permissions assigned to these actions are called "elevated permissions" and are: KickMembers, BanMembers, Administrator, ManageChannels, ManageGuild, ManageMessages, ManageRoles, ManageWebhooks, ManageThreads, and ManageGuildExpressions.

# Implicit permissions

Some Discord permissions apply implicitly based on logical use, which can cause unwanted behavior if you are not aware of this fact.

The prime example for implicit permissions is ViewChannel. If this flag is missing in the final permissions, you can't do anything on that channel. It makes sense, right? If you can't view the channel, you can't read or send messages in it, set the topic, or change its name. The library does not handle implicit permissions for you, so understanding how the system works is vital for you as a bot developer.

Let's say you want to send a message to a channel. To prevent unnecessary API calls, you want to make sure your bot's permissions in this channel include SendMessages (more on how to achieve this here). The check passes, but you still can't send the message and are greeted with DiscordAPIError: Missing Access.

This error means your bot is missing ViewChannel, and as such, can't send messages either.

One possible scenario causing this: the channel has permission overwrites for the default role @everyone to grant SendMessages so everyone who can see the channel can also write in it, but at the same time has an overwrite to deny ViewChannel to make it only accessible to a subset of members.

As you only check for SendMessages, the bot will try to execute the send, but since ViewChannel is missing, the API denies the request.

# Limitations and oddities

• Your bot needs ManageRoles in its base permissions to change base permissions.
• It needs ManageRoles in its final permissions to change permission overwrites.
• It cannot edit permissions for roles that are higher than or equal to its highest role.
• It cannot grant permissions it doesn't have.
• It can manage overwrites for roles or users with higher roles than its own highest role.
• It can manage overwrites for permissions it doesn't have.
• Members with the Administrator permission are not affected by overwrites at all.

# Missing permissions

During your development, you will likely run into DiscordAPIError: Missing Permissions at some point. One of the following can cause this error:

• Your bot is missing the needed permission to execute this action in its calculated base or final permissions (requirement changes based on the type of action you are trying to perform).
• You provided an invalid permission number while trying to create overwrites. (The calculator on the apps page returns decimal values while the developer documentation lists the flags in hex. Make sure you are not mixing the two and don't use the hex prefix 0x where not applicable).
• Your bot is currently timed out.
• It is trying to execute an action on a guild member with a role higher than or equal to your bot's highest role.
• It is trying to modify or assign a role higher than or equal to its highest role.
• It is trying to add a managed role to a member.
• It is trying to remove a managed role from a member.
• It is trying to timeout a member with the Administrator permission.
• It is trying to execute a forbidden action on the server owner.
• It is trying to execute an action based on another unfulfilled factor (for example, reserved for partnered guilds).
• It is trying to execute an action on a voice channel without the ViewChannel permission.
• It is trying to create a channel or channel overwrite including the ManageRoles flag but does not have the Administrator permission or an explicit ManageRoles overwrite on this channel (note that the global permission does not count).