Roles and permissions

How permissions are calculated

1. The server owner can do everything.
2. Otherwise start from the server's default permissions (@everyone).
3. Add the permissions of every role the member has (allow), then remove what roles deny, from the lowest to the highest ranked role.
4. In a channel, apply the channel's default override, then the role overrides, the same way.
5. A member in timeout keeps only View Channel and Read Message History.

Permissions are a 64-bit number; each permission is one bit. Use BigInt in JavaScript: a plain number cannot hold every bit exactly.

const SEND_MESSAGE = 1n << 22n;
const canSend =
  (BigInt(interaction.user_permissions_string) & SEND_MESSAGE) === SEND_MESSAGE;

Every interaction tells you the permissions of the person who used it (user_permissions_string) and of your bot (app_permissions_string) in that channel, so you rarely need to compute them yourself.

Permission strings

Endpoints in this reference name permissions such as Timeout Members. In an error the same permission is written TimeoutMembers, the first column of the table below. Add values to send several: Kick Members (64) and Ban Members (128) are 192.

Threads and forums

CreateThreads, SendMessageInThreads and CreateForumPosts are on for @everyone by default. Deny them on a role, or on a channel, and those people can only read. They are read on the parent channel, on top of Send Messages.

Ranking

Roles have a rank; a lower number ranks higher. A bot can only edit, give, take, kick, ban or time out members and roles that rank below its own highest role. Otherwise the server answers NotElevated. Ask server admins to move your bot's role up if your bot moderates.

Permission bits

Reference

PUT /channels/{target}/permissions/{role_id}

Set Role Permission. Sets permissions for the specified role in this channel. Channel must be a TextChannel.

Permissions: Channel:ManagePermissions · Rate limit: channels, 15 / 10 s

PUT /channels/{target}/permissions/default

Set Default Permission. Sets permissions for the default role in this channel. Channel must be a Group or TextChannel. A channel synced with its category stops following it: it keeps a copy of the category's permissions and the change applies on top.

Permissions: Channel:ManagePermissions · Rate limit: channels, 15 / 10 s

PUT /channels/{target}/permissions/members/{user_id}

Set Member Permission. Sets one member's permissions in this channel, applied after every role (for example a ticket only its author and the staff can see). An empty override (allow 0, deny 0) removes it. Channel must be a TextChannel. Needs Manage Permissions in the channel, a higher rank than the member, and only the permissions you hold yourself.

Permissions: Channel:ManagePermissions · Rate limit: channels, 15 / 10 s

POST /channels/{target}/permissions/sync

Sync Permissions With Category. The channel follows its category's permissions again; its own default and role overrides are cleared. Per-member overrides stay.

Permissions: Channel:ManagePermissions · Rate limit: channels, 15 / 10 s

PUT /servers/{target}/categories/{category_id}/permissions/{role_id}

Set Category Role Permission. Sets a role's permissions for a category. Channels synced with the category use them instead of their own. An empty override removes it.

Rate limit: servers, 5 / 10 s

PUT /servers/{target}/categories/{category_id}/permissions/default

Set Category Default Permission. Sets the default permissions for a category. Channels synced with the category use them instead of their own.

Rate limit: servers, 5 / 10 s

PUT /servers/{target}/permissions/{role_id}

Set Role Permission. Sets permissions for the specified role in the server.

Permissions: Channel:ManagePermissions · Rate limit: servers, 5 / 10 s

PUT /servers/{target}/permissions/default

Set Default Permission. Sets permissions for the default role in this server.

Permissions: Channel:ManagePermissions · Rate limit: servers, 5 / 10 s

POST /servers/{target}/roles

Create Role. Creates a new server role.

Permissions: Channel:ManageRole · Rate limit: servers, 5 / 10 s

DELETE /servers/{target}/roles/{role_id}

Delete Role. Delete a server role by its id.

Permissions: Channel:ManageRole · Rate limit: servers, 5 / 10 s

GET /servers/{target}/roles/{role_id}

Fetch Role. Fetch a role by its id.

Rate limit: servers, 5 / 10 s

PATCH /servers/{target}/roles/{role_id}

Edit Role. Edit a role by its id.

Permissions: Channel:ManageRole · Rate limit: servers, 5 / 10 s

PATCH /servers/{target}/roles/ranks

Edits server roles ranks. Edit's server role's ranks.

Permissions: Channel:ManageRole · Rate limit: servers, 5 / 10 s