Permissions

Learn how Discord’s permission system works, including bitwise permission flags, role hierarchy, channel overwrites, and how to compute effective permissions.

Permissions are a way to limit and grant certain abilities to users in Discord. A set of base permissions can be configured at the guild level for different roles. When these roles are attached to users, they grant or revoke specific privileges within the guild. Along with guild-level permissions, Discord also supports permission overwrites that can be assigned to individual roles or members on a per-channel basis.

Application command permissions allow you to enable or disable specific commands for entire channels in addition to individual roles or users.

Permissions are stored in a variable-length integer serialized into a string, and are calculated using bitwise operations. For example, the permission value 123 will be serialized as "123". For long-term stability, it’s recommended to deserialize permissions using your preferred language’s Big Integer libraries.

The total permissions integer can be determined by OR-ing (|) together each individual value, and flags can be checked using AND (&) operations:

# Permissions value that can Send Messages (0x800) and Add Reactions (0x40):
permissions = 0x40 | 0x800  # 2112

# Checking for flags that are set:
(permissions & 0x40) == 0x40    # True
(permissions & 0x800) == 0x800  # True

# Kick Members (0x2) was not set:
(permissions & 0x2) == 0x2  # False

In API v8 and above, all permissions are serialized as strings, including the allow and deny fields in overwrites.

Bitwise permission flags

Below is a table of all current permissions, their integer values in hexadecimal, brief descriptions of the privileges they grant, and the channel type they apply to.

Permission	Value	Description	Channel type
CREATE_INSTANT_INVITE	0x0000000000000001 (1 << 0)	Allows creation of instant invites	T, V, S
KICK_MEMBERS *	0x0000000000000002 (1 << 1)	Allows kicking members
BAN_MEMBERS *	0x0000000000000004 (1 << 2)	Allows banning members
ADMINISTRATOR *	0x0000000000000008 (1 << 3)	Allows all permissions and bypasses channel permission overwrites
MANAGE_CHANNELS *	0x0000000000000010 (1 << 4)	Allows management and editing of channels	T, V, S
MANAGE_GUILD *	0x0000000000000020 (1 << 5)	Allows management and editing of the guild
ADD_REACTIONS	0x0000000000000040 (1 << 6)	Allows for adding new reactions to messages. Does not apply to reacting with an existing reaction.	T, V, S
VIEW_AUDIT_LOG	0x0000000000000080 (1 << 7)	Allows for viewing of audit logs
PRIORITY_SPEAKER	0x0000000000000100 (1 << 8)	Allows for using priority speaker in a voice channel	V
STREAM	0x0000000000000200 (1 << 9)	Allows the user to go live	V, S
VIEW_CHANNEL	0x0000000000000400 (1 << 10)	Allows guild members to view a channel, including reading messages in text channels and joining voice channels	T, V, S
SEND_MESSAGES	0x0000000000000800 (1 << 11)	Allows for sending messages in a channel and creating threads in a forum (does not allow sending messages in threads)	T, V, S
SEND_TTS_MESSAGES	0x0000000000001000 (1 << 12)	Allows for sending of /tts messages	T, V, S
MANAGE_MESSAGES *	0x0000000000002000 (1 << 13)	Allows for deletion of other users’ messages	T, V, S
EMBED_LINKS	0x0000000000004000 (1 << 14)	Links sent by users with this permission will be auto-embedded	T, V, S
ATTACH_FILES	0x0000000000008000 (1 << 15)	Allows for uploading images and files	T, V, S
READ_MESSAGE_HISTORY	0x0000000000010000 (1 << 16)	Allows for reading of message history	T, V, S
MENTION_EVERYONE	0x0000000000020000 (1 << 17)	Allows for using the @everyone tag to notify all users in a channel, and the @here tag to notify all online users	T, V, S
USE_EXTERNAL_EMOJIS	0x0000000000040000 (1 << 18)	Allows the usage of custom emojis from other servers	T, V, S
VIEW_GUILD_INSIGHTS	0x0000000000080000 (1 << 19)	Allows for viewing guild insights
CONNECT	0x0000000000100000 (1 << 20)	Allows for joining of a voice channel	V, S
SPEAK	0x0000000000200000 (1 << 21)	Allows for speaking in a voice channel	V
MUTE_MEMBERS	0x0000000000400000 (1 << 22)	Allows for muting members in a voice channel	V, S
DEAFEN_MEMBERS	0x0000000000800000 (1 << 23)	Allows for deafening of members in a voice channel	V
MOVE_MEMBERS	0x0000000001000000 (1 << 24)	Allows for moving of members between voice channels	V, S
USE_VAD	0x0000000002000000 (1 << 25)	Allows for using voice-activity-detection in a voice channel	V
CHANGE_NICKNAME	0x0000000004000000 (1 << 26)	Allows for modification of own nickname
MANAGE_NICKNAMES	0x0000000008000000 (1 << 27)	Allows for modification of other users’ nicknames
MANAGE_ROLES *	0x0000000010000000 (1 << 28)	Allows management and editing of roles	T, V, S
MANAGE_WEBHOOKS *	0x0000000020000000 (1 << 29)	Allows management and editing of webhooks	T, V, S
MANAGE_GUILD_EXPRESSIONS *	0x0000000040000000 (1 << 30)	Allows for editing and deleting emojis, stickers, and soundboard sounds created by all users
USE_APPLICATION_COMMANDS	0x0000000080000000 (1 << 31)	Allows members to use application commands, including slash commands and context menu commands	T, V, S
REQUEST_TO_SPEAK	0x0000000100000000 (1 << 32)	Allows for requesting to speak in stage channels	S
MANAGE_EVENTS	0x0000000200000000 (1 << 33)	Allows for editing and deleting scheduled events created by all users	V, S
MANAGE_THREADS *	0x0000000400000000 (1 << 34)	Allows for deleting and archiving threads, and viewing all private threads	T
CREATE_PUBLIC_THREADS	0x0000000800000000 (1 << 35)	Allows for creating public and announcement threads	T
CREATE_PRIVATE_THREADS	0x0000001000000000 (1 << 36)	Allows for creating private threads	T
USE_EXTERNAL_STICKERS	0x0000002000000000 (1 << 37)	Allows the usage of custom stickers from other servers	T, V, S
SEND_MESSAGES_IN_THREADS	0x0000004000000000 (1 << 38)	Allows for sending messages in threads	T
USE_EMBEDDED_ACTIVITIES	0x0000008000000000 (1 << 39)	Allows for using Activities (applications with the EMBEDDED flag)	T, V
MODERATE_MEMBERS **	0x0000010000000000 (1 << 40)	Allows for timing out users to prevent them from sending or reacting to messages in chat and threads, and from speaking in voice and stage channels
VIEW_CREATOR_MONETIZATION_ANALYTICS *	0x0000020000000000 (1 << 41)	Allows for viewing role subscription insights
USE_SOUNDBOARD	0x0000040000000000 (1 << 42)	Allows for using soundboard in a voice channel	V
CREATE_GUILD_EXPRESSIONS	0x0000080000000000 (1 << 43)	Allows for creating emojis, stickers, and soundboard sounds, and editing and deleting those created by the current user
CREATE_EVENTS	0x0000100000000000 (1 << 44)	Allows for creating scheduled events, and editing and deleting those created by the current user	V, S
USE_EXTERNAL_SOUNDS	0x0000200000000000 (1 << 45)	Allows the usage of custom soundboard sounds from other servers	V
SEND_VOICE_MESSAGES	0x0000400000000000 (1 << 46)	Allows sending voice messages	T, V, S
SEND_POLLS	0x0002000000000000 (1 << 49)	Allows sending polls	T, V, S
USE_EXTERNAL_APPS	0x0004000000000000 (1 << 50)	Allows user-installed apps to send public responses. When disabled, responses will be ephemeral. Only applies to apps not also installed to the server.	T, V, S
PIN_MESSAGES	0x0008000000000000 (1 << 51)	Allows pinning and unpinning messages	T
BYPASS_SLOWMODE	0x0010000000000000 (1 << 52)	Allows bypassing slowmode restrictions	T, V, S

Channel type key

Abbreviation	Channel types
T	GUILD_TEXT, GUILD_ANNOUNCEMENT, GUILD_FORUM, GUILD_MEDIA
V	GUILD_VOICE
S	GUILD_STAGE_VOICE

* These permissions require the owner account to use two-factor authentication when used on a guild that has server-wide 2FA enabled.

** See Permissions for timed out members to understand how permissions are temporarily modified for timed out users.

Permission names may be referred to differently in the Discord client. For example, “Manage Permissions” refers to MANAGE_ROLES, “Use Voice Activity” refers to USE_VAD, and “Timeout Members” refers to MODERATE_MEMBERS.

Permission hierarchy

A bot’s or user’s highest role is the role with the greatest position value in the guild, with the default @everyone role starting at 0. Permissions follow these hierarchy rules:

• A bot can grant roles to other users that are of a lower position than its own highest role.
• A bot can edit roles of a lower position than its highest role, but it can only grant permissions it already has to those roles.
• A bot can only sort roles lower than its highest role.
• A bot can only kick, ban, and edit nicknames for users whose highest role is lower than the bot’s highest role.

Otherwise, permissions do not obey the role hierarchy. For example, if a user has two roles where role A denies VIEW_CHANNEL and role B allows VIEW_CHANNEL on a channel, the user will be able to view the channel regardless of role positions.

Permission overwrites

Overwrites can be used to apply certain permissions to roles or members on a channel level. When permission collisions occur, permissions are applied in the following order:

1. Base @everyone permissions

   Base permissions given to @everyone are applied at a guild level.

2. Role permissions

   Permissions allowed to a user by their roles are applied at a guild level.

3. @everyone channel overwrites

   Overwrites that deny permissions for @everyone are applied at a channel level, then overwrites that allow permissions for @everyone are applied.

4. Role-specific channel overwrites

   Overwrites that deny permissions for specific roles are applied, then overwrites that allow permissions for specific roles are applied.

5. Member-specific channel overwrites

   Member-specific overwrites that deny permissions are applied, then member-specific overwrites that allow permissions are applied.

The following pseudocode demonstrates this process:

def compute_base_permissions(member, guild):
    if guild.is_owner(member):
        return ALL

    role_everyone = guild.get_role(guild.id)  # get @everyone role
    permissions = role_everyone.permissions

    for role in member.roles:
        permissions |= role.permissions

    if permissions & ADMINISTRATOR == ADMINISTRATOR:
        return ALL

    return permissions

def compute_overwrites(base_permissions, member, channel):
    # ADMINISTRATOR overrides any potential permission overwrites
    if base_permissions & ADMINISTRATOR == ADMINISTRATOR:
        return ALL

    permissions = base_permissions
    overwrite_everyone = overwrites.get(channel.guild_id)  # Find (@everyone) role overwrite and apply it
    if overwrite_everyone:
        permissions &= ~overwrite_everyone.deny
        permissions |= overwrite_everyone.allow

    # Apply role specific overwrites
    overwrites = channel.permission_overwrites
    allow = NONE
    deny = NONE
    for role_id in member.roles:
        overwrite_role = overwrites.get(role_id)
        if overwrite_role:
            allow |= overwrite_role.allow
            deny |= overwrite_role.deny

    permissions &= ~deny
    permissions |= allow

    # Apply member specific overwrite if it exists
    overwrite_member = overwrites.get(member.user_id)
    if overwrite_member:
        permissions &= ~overwrite_member.deny
        permissions |= overwrite_member.allow

    return permissions

def compute_permissions(member, channel):
    base_permissions = compute_base_permissions(member, channel.guild)
    return compute_overwrites(base_permissions, member, channel)

Implicit permissions

Permissions in Discord are sometimes implicitly denied or allowed based on logical use:

• Denying VIEW_CHANNEL on a channel implicitly denies other permissions on that channel (like SEND_MESSAGES), even if those aren’t explicitly denied.
• Denying SEND_MESSAGES implicitly denies MENTION_EVERYONE, SEND_TTS_MESSAGES, ATTACH_FILES, and EMBED_LINKS.
• For voice and stage channels, denying CONNECT also implicitly denies other permissions such as MANAGE_CHANNEL.

Inherited permissions (threads)

Threads inherit permissions from the parent channel, with one exception: the SEND_MESSAGES permission is not inherited. Users must have SEND_MESSAGES_IN_THREADS to send a message in a thread.

Users must have the VIEW_CHANNEL permission to view any threads in the channel, even if they are directly mentioned or added to the thread.

Permission syncing

If a child channel has the same permissions and overwrites as its parent category, the channel is considered “synced” to the category. Further changes to a parent category will be reflected in its synced child channels. Any changes to a child channel will de-sync it from its parent category.

Role object

Roles represent a set of permissions attached to a group of users. Roles have names, colors, and can be “pinned” to the sidebar, causing their members to be listed separately. The @everyone role has the same ID as the guild it belongs to.

Role structure

Field	Type	Description
id	snowflake	Role ID
name	string	Role name
color*	integer	Deprecated integer representation of hexadecimal color code
colors	role colors object	The role’s colors
hoist	boolean	If this role is pinned in the user listing
icon?	?string	Role icon hash
unicode_emoji?	?string	Role unicode emoji
position	integer	Position of this role (roles with the same position are sorted by ID)
permissions	string	Permission bit set
managed	boolean	Whether this role is managed by an integration
mentionable	boolean	Whether this role is mentionable
tags?	role tags object	The tags this role has
flags	integer	Role flags combined as a bitfield

* color will still be returned by the API, but using the colors field is recommended.

Role tags structure

Tags with type null represent booleans. They will be present and set to null if true, and absent if false.

Field	Type	Description
bot_id?	snowflake	The ID of the bot this role belongs to
integration_id?	snowflake	The ID of the integration this role belongs to
premium_subscriber?	null	Whether this is the guild’s Booster role
subscription_listing_id?	snowflake	The ID of this role’s subscription SKU and listing
available_for_purchase?	null	Whether this role is available for purchase
guild_connections?	null	Whether this role is a guild’s linked role

Role colors object

Field	Type	Description
primary_color	integer	The primary color for the role
secondary_color	?integer	The secondary color for the role; creates a gradient when set
tertiary_color	?integer	The tertiary color for the role; turns the gradient into a holographic style when set

When sending tertiary_color, the API enforces holographic style with values: primary_color = 11127295, secondary_color = 16759788, tertiary_color = 16761760.

Role flags

Flag	Value	Description
IN_PROMPT	1 << 0	Role can be selected by members in an onboarding prompt

Example role

{
  "id": "41771983423143936",
  "name": "WE DEM BOYZZ!!!!!!",
  "color": 3447003,
  "colors": {
    "primary_color": 3447003,
    "secondary_color": null,
    "tertiary_color": null
  },
  "hoist": true,
  "icon": "cf3ced8600b777c9486c6d8d84fb4327",
  "unicode_emoji": null,
  "position": 1,
  "permissions": "66321471",
  "managed": false,
  "mentionable": false,
  "flags": 0
}

Permissions for timed out members

Timed out members temporarily lose all permissions except VIEW_CHANNEL and READ_MESSAGE_HISTORY. Guild owners and users with the ADMINISTRATOR permission are exempt from timeouts.