Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
18.3 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Roles and permissions
description: The permission bits, how Fluxer computes a member's permissions and the routes that manage guild roles.
---

import RouteHeader from '@/components/RouteHeader.astro';

A permission lets a member do one thing in a guild, such as send a message or ban another member. Each role grants a set of permissions as a 64-bit mask, and a [permission overwrite](/http-api/channels/#permission-overwrite-object) on a channel changes that set for one channel.

## Permissions

| Value | Name | Description |
| --- | --- | --- |
| 1 << 0 | CREATE_INSTANT_INVITE | Create an invite to a guild channel |
| 1 << 1 | KICK_MEMBERS | Remove a member from the guild |
| 1 << 2 | BAN_MEMBERS | Ban and unban members |
| 1 << 3 | ADMINISTRATOR | Grants every permission and ignores every channel overwrite |
| 1 << 4 | MANAGE_CHANNELS | Create, modify, reorder and delete guild channels |
| 1 << 5 | MANAGE_GUILD | Modify guild settings, invites, the vanity URL and discovery |
| 1 << 6 | ADD_REACTIONS | Add a reaction to a message |
| 1 << 7 | VIEW_AUDIT_LOG | Read the guild audit log |
| 1 << 8 | PRIORITY_SPEAKER | Use priority speaker in a voice channel, enforced by the client |
| 1 << 9 | STREAM | Share your screen or camera in a voice channel |
| 1 << 10 | VIEW_CHANNEL | View a channel |
| 1 << 11 | SEND_MESSAGES | Send messages, create forum posts and publish your own announcements |
| 1 << 12 | SEND_TTS_MESSAGES | Send a text-to-speech message |
| 1 << 13 | MANAGE_MESSAGES | Delete other members' messages and reactions, bulk delete messages and edit other members' message flags and attachments |
| 1 << 14 | EMBED_LINKS | Have links in your messages expanded into embeds |
| 1 << 15 | ATTACH_FILES | Attach files to a message |
| 1 << 16 | READ_MESSAGE_HISTORY | Read messages older than the guild's `message_history_cutoff`, or any message when the guild has no cutoff |
| 1 << 17 | MENTION_EVERYONE | Use the everyone and here mentions |
| 1 << 18 | USE_EXTERNAL_EMOJIS | Use emojis from other guilds |
| 1 << 20 | CONNECT | Connect to a voice channel |
| 1 << 21 | SPEAK | Talk in a voice channel |
| 1 << 22 | MUTE_MEMBERS | Mute other members in a voice channel |
| 1 << 23 | DEAFEN_MEMBERS | Deafen other members in a voice channel |
| 1 << 24 | MOVE_MEMBERS | Move members between voice channels or disconnect them |
| 1 << 25 | USE_VAD | Use voice activity detection, enforced by the client |
| 1 << 26 | CHANGE_NICKNAME | Change your own nickname |
| 1 << 27 | MANAGE_NICKNAMES | Change other members' nicknames |
| 1 << 28 | MANAGE_ROLES | Manage roles below your highest role, assign them and set channel overwrites |
| 1 << 29 | MANAGE_WEBHOOKS | Create, modify and delete webhooks and follow announcement channels |
| 1 << 30 | MANAGE_EXPRESSIONS | Modify and delete emojis and stickers that other members created |
| 1 &lt;&lt; 34 | MANAGE_THREADS<sup>1</sup> | Archive, lock, rename and delete threads and see every private thread |
| 1 &lt;&lt; 35 | CREATE_PUBLIC_THREADS<sup>1</sup> | Start public and announcement threads |
| 1 &lt;&lt; 36 | CREATE_PRIVATE_THREADS<sup>1</sup> | Start private threads |
| 1 &lt;&lt; 37 | USE_EXTERNAL_STICKERS | Use stickers from other guilds |
| 1 &lt;&lt; 38 | SEND_MESSAGES_IN_THREADS<sup>1</sup> | Send messages in threads and add members to them |
| 1 &lt;&lt; 40 | MODERATE_MEMBERS | Time out members |
| 1 &lt;&lt; 43 | CREATE_EXPRESSIONS | Create emojis and stickers and edit or delete your own |
| 1 &lt;&lt; 51 | PIN_MESSAGES | Pin and unpin messages |
| 1 &lt;&lt; 52 | BYPASS_SLOWMODE | Ignore the channel slowmode |
| 1 &lt;&lt; 53 | UPDATE_RTC_REGION | Change the voice region of a voice channel |
| 1 &lt;&lt; 54 | VIEW_CHANNEL_MEMBERS<sup>1</sup> | View the member list of a channel |

<sup>1</sup> The bit is [feature-gated](#feature-gated-permission-bits). [Thread permissions](/http-api/threads/#thread-permissions) explains how the thread bits apply.

Responses send a permission mask as a decimal string. Requests accept a decimal string up to 9223372036854775807, or a JSON number that is a safe integer. Parse masks as unsigned 64-bit integers. Fluxer drops any bit it doesn't define.

### Feature-gated permission bits

You can only write a gated bit when your request declares the feature it needs, in the `X-Fluxer-Features` header as a comma-separated list.

| Bits | Who can write them |
| --- | --- |
| `VIEW_CHANNEL_MEMBERS` | A request that declares `view_channel_members_permission` |
| The four thread bits | A bot, or a user session that declares the [`channel_threads`](/http-api/threads/#client-capability) feature |

When you can't write a gated bit, Fluxer keeps that bit at its stored value and writes the rest of the mask. A new role created with `permissions` starts with the bit cleared. One created without `permissions` copies the everyone role's mask, gated bits included. Callers that can't write the thread bits also don't see them in role masks, overwrite masks or `permissions` values.

## Elevated permissions

`KICK_MEMBERS`, `BAN_MEMBERS`, `ADMINISTRATOR`, `MANAGE_CHANNELS`, `MANAGE_GUILD`, `MANAGE_MESSAGES`, `MANAGE_ROLES`, `MANAGE_WEBHOOKS`, `MODERATE_MEMBERS` and `MANAGE_THREADS` are elevated. In a guild with the elevated [MFA level](/http-api/guilds/#mfa-levels), a member other than the owner needs two-factor authentication to use them, and gets 400 `TWO_FACTOR_REQUIRED` without it. Computed `permissions` values still include these bits.

## Permission computation

The guild owner has every permission, and a user who isn't a member has none. For anyone else, Fluxer starts with the everyone role, whose ID is the guild ID, and adds every role the member has. If the result has `ADMINISTRATOR`, the member has every permission and no overwrite applies.

In a channel, Fluxer then applies the channel's overwrites in this order, removing denied bits before adding allowed bits at each step.

1. The everyone role overwrite.
2. The overwrites for the member's roles, combined, where an allow on one role beats a deny on another.
3. The member's own overwrite.

A category is visible when you can view at least one channel in it. A thread has no overwrites of its own, and [Thread permissions](/http-api/threads/#thread-permissions) explains how its permissions work.

## Communication timeout

In a guild channel, a member whose [`communication_disabled_until`](/http-api/guild-members/#guild-member-object) is in the future keeps their permissions, but gets 403 `COMMUNICATION_DISABLED` when they try any of these.

- Send, edit or publish their own message
- Add a reaction or request an attachment upload
- Start typing
- Change their own nickname
- Start, change or delete a thread, or add or remove its members
- Pin or unpin a message in a thread

Check `communication_disabled_until` as well as the mask before you show these actions.

## Role hierarchy

Roles rank by `position`, and your rank is the rank of your highest role. You can manage a role only when you rank above it, even with `MANAGE_ROLES`, and the guild owner can manage every role.

A role or overwrite write that grants a permission you don't have fails with `MISSING_PERMISSIONS`, unless you're the guild owner.

## Guild role object

A role is a permission mask that a guild assigns to its members.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the role |
| name | string | The name of the role (1-100 characters) |
| color | integer | The color of the role as an RGB integer (0-16777215) |
| position | integer | The rank of the role, where a larger value ranks higher |
| hoist_position | ?integer | The position of the role's group in the member list, or null to follow `position` |
| permissions | decimal string | The [permission](#permissions) mask the role grants |
| hoist | boolean | Whether the role's members show as their own group in the member list |
| mentionable | boolean | Whether members without `MENTION_EVERYONE` can mention the role |
| icon | ?string | The hash of the role icon image, or null |
| unicode_emoji | ?string | The Unicode emoji used as the role icon, or null |

The everyone role has the guild's ID, is called `@everyone` and is always at position 0. You can change its color and permissions, but you can't delete it, move it, give it a hoist position or give it an icon.

A role has at most one of `icon` and `unicode_emoji`. Clients show the icon of a member's highest role that has one. An image icon is served by the Media Proxy at [Get role icon](/media-proxy/routes/#get-role-icon).

### Example

```json
{
  "id": "1489002177550843904",
  "name": "Moderator",
  "color": 3447003,
  "position": 4,
  "hoist_position": 1,
  "permissions": "1099511637006",
  "hoist": true,
  "mentionable": false,
  "icon": "5d4c7a1e",
  "unicode_emoji": null
}
```

## Role position object

One entry in a [Modify guild role positions](#modify-guild-role-positions) request.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the role |
| position? | integer | The rank you want for the role, where a larger value ranks higher |

## Role hoist position object

One entry in a [Modify role hoist positions](#modify-role-hoist-positions) request.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the role |
| hoist_position | integer | The member list position to give the role |

## List guild roles

<RouteHeader method="GET" path="/v1/guilds/{guild_id}/roles" bot oauth2="guilds" />

Returns every [guild role object](#guild-role-object) in the guild, highest `position` first. You need to be a member of the guild, and an OAuth2 token needs the `guilds` scope.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[guild role](#guild-role-object) object] | The roles were returned |

The rate limit is 60 requests per 10 seconds, on the `guild:role:list::guild_id` bucket.

## Create guild role

<RouteHeader method="POST" path="/v1/guilds/{guild_id}/roles" bot auditReason />

Creates a role at position 1 and returns its [guild role object](#guild-role-object). You need [MANAGE_ROLES](#elevated-permissions). Fluxer sends a [Guild Role Create](/gateway/events/#guild-role-create) event.

### Request headers

| Field | Type | Description |
| --- | --- | --- |
| X-Fluxer-Features? | string | A comma-separated [feature declaration](#feature-gated-permission-bits) |

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| name | string | The name of the role (1-100 characters) |
| color? | integer | The color of the role as an RGB integer (0-16777215, default 0) |
| permissions? | decimal string \| integer | The [permission](#permissions) mask, which defaults to the everyone role's mask |
| icon? | ?base64 string | A PNG, JPEG, WebP or AVIF image for the [role icon](#role-icons), or null to remove it |
| unicode_emoji? | ?string | A single Unicode emoji for the role icon, or null to remove it |
| icon_source_role_id? | snowflake | A role in this guild whose icon the new role copies |


With `icon_source_role_id`, Fluxer stores a separate copy of an image icon. Deleting either role leaves the other's icon in place.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild role object](#guild-role-object) | The role was created |
| 400 | [error response](/http-api/#error-response) | `MAX_GUILD_ROLES` when the guild is at its role limit, 250 by default, counting the everyone role |
| 400 | [error response](/http-api/#error-response) | A [role icon](#role-icons) is not valid |
| 400 | [error response](/http-api/#error-response) | `ROLE_ICON_SOURCE_AND_ICON_EXCLUSIVE` when `icon_source_role_id` comes with `icon` or `unicode_emoji` |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_ROLE` when `icon_source_role_id` is not a role in this guild |
| 413 | [error response](/http-api/#error-response) | The body is larger than a role icon allows |

The rate limit is 10 requests per minute, on the `guild:role:create::guild_id` bucket.

## Modify guild role

<RouteHeader method="PATCH" path="/v1/guilds/{guild_id}/roles/{role_id}" bot auditReason />

Modifies a role and returns its [guild role object](#guild-role-object). You need [MANAGE_ROLES](#elevated-permissions) and must [outrank](#role-hierarchy) the role. Fluxer sends a [Guild Role Update](/gateway/events/#guild-role-update) event.

### Request headers

| Field | Type | Description |
| --- | --- | --- |
| X-Fluxer-Features? | string | A comma-separated [feature declaration](#feature-gated-permission-bits) |

### JSON body

Fields you leave out keep their value. On the everyone role, Fluxer ignores every field except `color`, `permissions`, `icon` and `unicode_emoji`, and the last two can only be null.

| Field | Type | Description |
| --- | --- | --- |
| name? | string | The name of the role (1-100 characters) |
| color? | integer | The color of the role as an RGB integer (0-16777215) |
| permissions? | decimal string \| integer | The new [permission](#permissions) mask, which replaces the old one |
| hoist? | boolean | Whether the role's members show as their own group in the member list |
| hoist_position? | ?integer | The member list position to give the role, or null to clear it |
| mentionable? | boolean | Whether members without `MENTION_EVERYONE` can mention the role |
| icon? | ?base64 string | A PNG, JPEG, WebP or AVIF image for the [role icon](#role-icons), or null to remove it |
| unicode_emoji? | ?string | A single Unicode emoji for the role icon, or null to remove it |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild role object](#guild-role-object) | The role was modified |
| 400 | [error response](/http-api/#error-response) | A [role icon](#role-icons) is not valid |
| 413 | [error response](/http-api/#error-response) | The body is larger than a role icon allows |

The rate limit is 20 requests per 10 seconds, on the `guild:role:update::guild_id` bucket.

### Role icons

Create guild role and Modify guild role take the same two icon fields.

| Body | Result |
| --- | --- |
| field left out | The icon stays as it is |
| `icon` with an image | The image is stored and `unicode_emoji` is cleared |
| `unicode_emoji` with an emoji | The emoji is stored and any image is cleared |
| `icon` set to null | The image is cleared |
| `unicode_emoji` set to null | The emoji is cleared |
| both non-null | 400 with `ROLE_ICON_AND_EMOJI_EXCLUSIVE` on `icon` |
| either non-null on the everyone role | 400 with `CANNOT_SET_ICON_ON_EVERYONE_ROLE` on that field |

An image can't be animated, can be at most 256 KiB and each side must be between 32 and 1024 pixels. An image outside these limits returns 400 with `IMAGE_SIZE_EXCEEDS_LIMIT`, `INVALID_IMAGE_FORMAT` or `IMAGE_DIMENSIONS_OUT_OF_RANGE`, and an emoji that isn't a single Unicode emoji returns `NOT_A_VALID_UNICODE_EMOJI`. Role icons are free and need no guild feature. When an image is replaced or cleared, or the role is deleted, Fluxer deletes the old image later.

## Modify guild role positions

<RouteHeader method="PATCH" path="/v1/guilds/{guild_id}/roles" bot auditReason />

Reorders roles and returns 204. You need [MANAGE_ROLES](#elevated-permissions) and must [outrank](#role-hierarchy) every role whose position you change. Fluxer sends a [Guild Role Update Bulk](/gateway/events/#guild-role-update-bulk) event with the stored positions.

Fluxer sorts the roles you can manage by the positions you send and keeps roles you can't manage at their rank. It then renumbers every role except the everyone role from 1, so the stored `position` can differ from the one you sent.

### JSON body

An array of [role position objects](#role-position-object). The everyone role can't be in it.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The positions were applied |
| 400 | [error response](/http-api/#error-response) | An entry is the everyone role or a role that doesn't exist |
| 423 | [error response](/http-api/#error-response) | Another position change is still running |

The rate limit is 20 requests per 10 seconds, on the `guild:role:positions::guild_id` bucket.

## Modify role hoist positions

<RouteHeader method="PATCH" path="/v1/guilds/{guild_id}/roles/hoist-positions" bot auditReason />

Sets the member list position of one or more roles and returns 204. You need [MANAGE_ROLES](#elevated-permissions) and must [outrank](#role-hierarchy) every role you name. Fluxer sends a [Guild Role Update Bulk](/gateway/events/#guild-role-update-bulk) event.

### JSON body

An array of [role hoist position objects](#role-hoist-position-object). The everyone role can't be in it.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The hoist positions were applied |
| 400 | [error response](/http-api/#error-response) | An entry is the everyone role or a role that doesn't exist |
| 423 | [error response](/http-api/#error-response) | Another hoist position change is still running |

The rate limit is 20 requests per 10 seconds, on the `guild:role:hoist_positions::guild_id` bucket.

## Reset role hoist positions

<RouteHeader method="DELETE" path="/v1/guilds/{guild_id}/roles/hoist-positions" bot auditReason />

Clears the member list position of every role in the guild, including roles you don't outrank, and returns 204. You need [MANAGE_ROLES](#elevated-permissions). Fluxer sends a [Guild Role Update Bulk](/gateway/events/#guild-role-update-bulk) event.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The hoist positions were cleared |
| 423 | [error response](/http-api/#error-response) | Another hoist position change is still running |

The rate limit is 10 requests per minute, on the `guild:role:hoist_positions_reset::guild_id` bucket.

## Delete guild role

<RouteHeader method="DELETE" path="/v1/guilds/{guild_id}/roles/{role_id}" bot auditReason />

Deletes a role, removes it from every member who has it and returns 204. You need [MANAGE_ROLES](#elevated-permissions) and must [outrank](#role-hierarchy) the role. You can't delete the everyone role. Fluxer sends a [Guild Role Delete](/gateway/events/#guild-role-delete) event.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The role was deleted |

The rate limit is 10 requests per minute, on the `guild:role:delete::guild_id` bucket.