Document permission splits for expressions and events (discord#6305)

* Document permission splits for expressions and events * Added info callout for docs delay --------- Co-authored-by: Colin Loretz <[email protected]>
Jupith · May 14, 2024 · f0a13f1 · f0a13f1
1 parent 021e162
commit f0a13f1
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 29 deletions.
diff --git a/docs/Change_Log.md b/docs/Change_Log.md
@@ -95,6 +95,23 @@ The public spec can be found in the new [`discord-api-spec` repository on GitHub
 
 Read the [media channel topic](#DOCS_TOPICS_THREADS/media-channels) for more information on the relevant APIs and technical details, or the [media channel Help Center Article](https://creator-support.discord.com/hc/en-us/articles/14346342766743) for more about the feature.
 
+## Permission Splits for Expressions and Events
+
+#### Jul 11, 2023
+
+> danger
+> This entry includes breaking changes
+
+> info
+> This documentation was unintentionally delayed from the release of the permission split.
+
+The `MANAGE_GUILD_EXPRESSIONS` and `MANAGE_EVENTS` [permissions](#DOCS_TOPICS_PERMISSIONS/permissions) no longer allow for creating new expressions and events. New permissions have been added:
+
+* `CREATE_GUILD_EXPRESSIONS`: `1 << 43`
+* `CREATE_EVENTS`: `1 << 44`
+
+These allow for creating new expressions/events, as well as editing and deleting those created by the current user. They have been enabled by default for roles with the corresponding Manage permissions and for `@everyone` in small servers, and they are enabled by default for `@everyone` in new servers.
+
 ## Add Join Raid and Mention Raid fields
 
 #### May 05, 2023

diff --git a/docs/resources/Emoji.md b/docs/resources/Emoji.md
@@ -79,15 +79,15 @@ Emojis cannot be converted between normal and premium after creation.
 
 ## List Guild Emojis % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis
 
-Returns a list of [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) objects for the given guild.
+Returns a list of [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) objects for the given guild. Includes `user` fields if the bot has the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission.
 
 ## Get Guild Emoji % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis/{emoji.id#DOCS_RESOURCES_EMOJI/emoji-object}
 
-Returns an [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object for the given guild and emoji IDs.
+Returns an [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object for the given guild and emoji IDs. Includes the `user` field if the bot has the `MANAGE_GUILD_EXPRESSIONS` permission, or if the bot created the emoji and has the the `CREATE_GUILD_EXPRESSIONS` permission.
 
 ## Create Guild Emoji % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis
 
-Create a new emoji for the guild. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the new [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event.
+Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event.
 
 > warn
 > Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a [JSON status code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/json).
@@ -105,7 +105,7 @@ Create a new emoji for the guild. Requires the `MANAGE_GUILD_EXPRESSIONS` permis
 
 ## Modify Guild Emoji % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis/{emoji.id#DOCS_RESOURCES_EMOJI/emoji-object}
 
-Modify the given emoji. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event.
+Modify the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event.
 
 > info
 > All parameters to this endpoint are optional.
@@ -122,7 +122,7 @@ Modify the given emoji. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Retu
 
 ## Delete Guild Emoji % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis/{emoji.id#DOCS_RESOURCES_EMOJI/emoji-object}
 
-Delete the given emoji. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event.
+Delete the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event.
 
 > info
 > This endpoint supports the `X-Audit-Log-Reason` header.
diff --git a/docs/resources/Guild_Scheduled_Event.md b/docs/resources/Guild_Scheduled_Event.md
@@ -236,38 +236,60 @@ NOTE: `entity_type` is expressed by name rather than value for readability
 > A user must be a member of the guild in order to access events for that guild unless the guild is lurkable. If a guild is lurkable,
 > events in that guild may be visible to lurkers depending on the event type and the permissions of any channels associated with the event.
 
-### Permissions to create an event with entity_type: STAGE_INSTANCE
+### Permissions for events with entity_type: STAGE_INSTANCE
 
-#### Write Permissions (CREATE / UPDATE)
+The computed permissions for the user in the `channel_id` associated with the event must include:
 
-- `MANAGE_EVENTS` at the guild level or at least `MANAGE_EVENTS` for the `channel_id` associated with the event
+#### Get Permissions
+
+- `VIEW_CHANNEL`
+
+#### Create Permissions
+
+- `CREATE_EVENTS`
 - `MANAGE_CHANNELS`
 - `MUTE_MEMBERS`
 - `MOVE_MEMBERS`
 
-#### Read Permissions (GET)
+#### Modify/Delete Permissions
+
+- If the event was created by the current user, either `CREATE_EVENTS` or `MANAGE_EVENTS`. Otherwise, `MANAGE_EVENTS`
+- `MANAGE_CHANNELS`
+- `MUTE_MEMBERS`
+- `MOVE_MEMBERS`
+
+### Permissions for events with entity_type: VOICE
+
+The computed permissions for the user in the `channel_id` associated with the event must include:
+
+#### Get Permissions
+
+- `VIEW_CHANNEL`
 
-- `VIEW_CHANNEL` for `channel_id` associated with the event
+#### Create permissions
 
-### Permissions to create an event with entity_type: VOICE
+- `CREATE_EVENTS`
+- `VIEW_CHANNEL`
+- `CONNECT`
 
-#### Write Permissions (CREATE / UPDATE)
+#### Modify/Delete Permissions
 
-- `MANAGE_EVENTS` at the guild level or `MANAGE_EVENTS` for the `channel_id` associated with the event
-- `VIEW_CHANNEL` for `channel_id` associated with event
-- `CONNECT` for `channel_id` associated with event
+- If the event was created by the current user, either `CREATE_EVENTS` or `MANAGE_EVENTS`. Otherwise, `MANAGE_EVENTS`
+- `VIEW_CHANNEL`
+- `CONNECT`
 
-#### Read Permissions (GET)
+### Permissions for events with entity_type: EXTERNAL
 
-- `VIEW_CHANNEL` for `channel_id` associated with the event
+The user's guild-level permissions must include:
 
+#### Get Permissions
 
-### Permissions to create an event with entity_type: EXTERNAL
+- *No permissions required*
 
-#### Write Permissions (CREATE / UPDATE)
+#### Create permissions
 
-- `MANAGE_EVENTS` at the guild level
+- `CREATE_EVENTS`
 
-#### Read Permissions (GET)
+#### Modify/Delete Permissions
 
-* *No other permissions required*
+- If the event was created by the current user, either `CREATE_EVENTS` or `MANAGE_EVENTS`. Otherwise, `MANAGE_EVENTS`
diff --git a/docs/resources/Sticker.md b/docs/resources/Sticker.md
@@ -114,15 +114,15 @@ Returns a list of available sticker packs.
 
 ## List Guild Stickers % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers
 
-Returns an array of [sticker](#DOCS_RESOURCES_STICKER/sticker-object) objects for the given guild. Includes `user` fields if the bot has the `MANAGE_GUILD_EXPRESSIONS` permission.
+Returns an array of [sticker](#DOCS_RESOURCES_STICKER/sticker-object) objects for the given guild. Includes `user` fields if the bot has the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission.
 
 ## Get Guild Sticker % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers/{sticker.id#DOCS_RESOURCES_STICKER/sticker-object}
 
-Returns a [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object for the given guild and sticker IDs. Includes the `user` field if the bot has the `MANAGE_GUILD_EXPRESSIONS` permission.
+Returns a [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object for the given guild and sticker IDs. Includes the `user` field if the bot has the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission.
 
 ## Create Guild Sticker % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers
 
-Create a new sticker for the guild. Send a `multipart/form-data` body. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the new [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event.
+Create a new sticker for the guild. Send a `multipart/form-data` body. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event.
 
 Every guilds has five free sticker slots by default, and each Boost level will grant access to more slots.
 
@@ -146,7 +146,7 @@ Every guilds has five free sticker slots by default, and each Boost level will g
 
 ## Modify Guild Sticker % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers/{sticker.id#DOCS_RESOURCES_STICKER/sticker-object}
 
-Modify the given sticker. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event.
+Modify the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event.
 
 > info
 > All parameters to this endpoint are optional.
@@ -164,7 +164,7 @@ Modify the given sticker. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Re
 
 ## Delete Guild Sticker % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers/{sticker.id#DOCS_RESOURCES_STICKER/sticker-object}
 
-Delete the given sticker. Requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event.
+Delete the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event.
 
 > info
 > This endpoint supports the `X-Audit-Log-Reason` header.
diff --git a/docs/topics/Permissions.md b/docs/topics/Permissions.md
@@ -62,10 +62,10 @@ Below is a table of all current permissions, their integer values in hexadecimal
 | 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 management and editing of emojis, stickers, and soundboard sounds                                                                            |              |
+| 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. (_This permission is under active development and may be changed or removed._)                    | S            |
-| MANAGE_EVENTS                          | `0x0000000200000000` `(1 << 33)` | Allows for creating, editing, and deleting scheduled events                                                                                         | V, 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            |
@@ -75,6 +75,8 @@ Below is a table of all current permissions, their integer values in hexadecimal
 | 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      |