Permissions

Permissions are a bitmask: each permission is one bit, a role's permissions is the OR of the bits it grants, and a member's permissions are the OR of their roles'. The same numbers appear in role objects, room overrides, the permissions parameter of install links, and GET /users/@me/spaces.

Add the values of the bits you need to build a mask; test a bit with (mask & bit) !== 0.

The bits#

New permissions are only ever appended; existing values never change meaning.

Useful masks#

How permissions resolve#

For a member in a space:

1. Owner? The space owner has every permission, always.
2. Space-wide mask = @everyone.permissions | role₁.permissions | role₂.permissions … over the member's roles.
3. Administrator? If bit 11 is set, the member has every permission in every room; stop here.
4. Room overrides, applied in order to the space-wide mask for that room: the @everyone override, then overrides of the member's other roles (every deny first, then every allow), then the member's own user override (deny, then allow). Overrides can only touch room-scoped bits.
5. Threads have no overrides of their own: a thread resolves against its channel's effective overrides (and so a synced section's), with the thread bits above on top. A private thread yields no permissions at all to anyone who is neither a member nor a Manage Threads holder.
6. Two implicit rules, the same as Discord's: without View Room the member has no permission at all in that room, whatever the bits say; and without Send Messages they cannot Attach Files or Mention @everyone either.

Administrator also grants every space-scoped permission for management actions (adding bots, editing the space, invites, emoji, roles, nicknames, kicks and bans), though role hierarchy still applies to Administrators - only the owner is above it.

GET /users/@me/spaces and the permissions of a space in READY give you step 2; to know what a bot may do in a room, apply that room's permission_overrides and user_overrides from READY.space_rooms (or GET /spaces/:id/rooms) yourself, or simply try the call and handle 403.

Room overrides#

A room can allow or deny room-scoped bits per role or per member, independent of the space-wide mask. Each override is {allow, deny}; a bit in deny removes the permission for that role in that room, a bit in allow grants it, and a bit in neither leaves the space-wide value. Text rooms accept the text bits (0–6 and 23); voice rooms accept View Room and the voice bits (15–22). Managing overrides needs Manage Roles, and you cannot grant through an override what you do not hold yourself.

Hierarchy#

Roles are ordered by position: @everyone is always 0, the custom roles hold unique positions from 1 up, and higher outranks lower. A member's rank is their highest role's position. The rules are Discord's, and they bind everyone but the owner - Administrators included:

• Roles: you can only create, edit, reorder or delete roles below your rank.
• Giving or taking a role depends only on the role. You can give anyone a role below your rank, or take one away - the owner, and members ranked above you, included. Roles the member holds at or above your rank are kept as they are.
• Kicking, banning and nicknames depend on the member: you can only kick or ban members whose rank is below yours, and only change the nickname of (or reset the space profile of) members whose rank is below yours. Only the owner can change the owner's; nobody can kick or ban the owner.
• You can only grant permission bits you hold yourself (Administrators hold all), on roles and in room overrides.
• You may always edit your own roles within those rules - including the owner, which is how they give themselves a colour.
• A bot's managed role is never given to anyone else, nor taken from its bot.

A bot follows the same rules: to give out a role it needs Manage Roles and a role above that role, and to kick or ban someone a role above theirs - see Bots › Giving people roles.

Positions#

• A new role goes in at position 1, just above @everyone - so whoever creates a role (a moderator, a bot) ranks above it and can manage it. Only the unbroken run of roles directly above it moves up one to make room; roles above a gap in the positions keep theirs. Read the new positions from the response and the SPACE_UPDATE that carries them rather than working them out.
• Moving one role (PATCH /spaces/:id/roles/:roleId with position) swaps it with the role holding that position, or puts it there as sent when no role holds it.
• Moving several roles at once (PATCH /spaces/:id/roles) puts each listed role in its slot; the role there, and any above it in the way, move up one, and every role not listed keeps its order around them. It is all or nothing - use it for any reorder of more than one role.
• Either way, no two roles ever share a position.
• Two roles with the same position - possible only in data from an instance that predates unique positions - rank by id: the newer one is lower.

Bots and permissions#

• An install link's permissions value becomes the bot's managed role, inserted at position 1 (just above @everyone) so the person who installed it outranks it. The installer can uncheck bits on the consent page, and the server drops any bit they do not hold themselves. Administrators and the owner can grant everything.
• Because the managed role starts at the bottom, a bot that gives out roles can at first only give out roles created after it. Drag its role above the roles it should hand out, under Space settings → Roles - see Bots › Giving people roles.
• The managed role can be edited afterwards like any other, moved up if the bot must give out roles or outrank people it moderates, and shows a bot badge. It cannot be deleted or given to anyone else; it disappears when the bot leaves.
• Additional roles can be assigned to the bot normally.
• Re-approving the install link re-applies the requested bits to the managed role - the way to change a bot's permissions from a link.