diff --git a/docs/Change_Log.md b/docs/Change_Log.md index c403f5a5f0..f66fc0e956 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -35,7 +35,7 @@ Application command permissions have been updated to add more granular control a #### Breaking changes - Bearer tokens are now required to edit command permissions. Bearer tokens are tokens tied to an authenticating user's permissions, and can be [retrieved using OAuth](#DOCS_TOPICS_OAUTH2). The user must have permission to manage the guild and roles. -- [`applications.commands.permissions.update`](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) scope was added as a requirement to edit command permissions. +- [`applications.commands.permissions.update`](#DOCS_TOPICS_OAUTH2/oauth2-scopes) scope was added as a requirement to edit command permissions. - Disabled the batch editing endpoint ([`PUT /applications/{application.id}/guilds/{guild.id}/commands/permissions`](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/batch-edit-application-command-permissions)). #### Other changes diff --git a/docs/Getting_Started.md b/docs/Getting_Started.md index 2fc0f87670..6157a2141c 100644 --- a/docs/Getting_Started.md +++ b/docs/Getting_Started.md @@ -65,7 +65,7 @@ For now, we’ll just add two scopes: - `applications.commands` lets your app create commands in guilds its installed - `bot` is to enable your bot user. After you click bot, you can also add different user permissions to the bot. For now, just check **Send Messages**. -See a list of all [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes), or read more on [user permissions](#DOCS_TOPICS_PERMISSIONS) in the documentation. +See a list of all [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/oauth2-scopes), or read more on [user permissions](#DOCS_TOPICS_PERMISSIONS) in the documentation. ![URL generator screenshot](url-generator.png) diff --git a/docs/interactions/Application_Commands.md b/docs/interactions/Application_Commands.md index ce7163ac2c..535a7d65e6 100644 --- a/docs/interactions/Application_Commands.md +++ b/docs/interactions/Application_Commands.md @@ -261,7 +261,7 @@ Application command permissions allow your app to enable or disable commands for A command's current permissions can be retrieved using the [`GET /applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions`](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/get-application-command-permissions) endpoint. The response will include an array called `permissions` with associated IDs and permission types. -Command permissions can be updated with the [`PUT /applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions`](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/edit-application-command-permissions) endpoint. To call the endpoint, apps must use a Bearer token that's authorized with the [`applications.commands.permissions.update`](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) scope from a user with sufficient permissions. For their permissions to be considered sufficient, all of the following must be true for **the authenticating user** (not your app or bot user): +Command permissions can be updated with the [`PUT /applications/{application.id}/guilds/{guild.id}/commands/{command.id}/permissions`](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/edit-application-command-permissions) endpoint. To call the endpoint, apps must use a Bearer token that's authorized with the [`applications.commands.permissions.update`](#DOCS_TOPICS_OAUTH2/oauth2-scopes) scope from a user with sufficient permissions. For their permissions to be considered sufficient, all of the following must be true for **the authenticating user** (not your app or bot user): - Has [permission to Manage Guild and Manage Roles](#DOCS_TOPICS_PERMISSIONS) in the guild where the command is being edited - Has the ability to run the command being edited - Has permission to manage the resources that will be affected (roles, users, and/or channels depending on the [permission types](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-permissions-object-application-command-permission-type)) diff --git a/docs/resources/Application.md b/docs/resources/Application.md index e753aa4fa6..7c4d840bd2 100644 --- a/docs/resources/Application.md +++ b/docs/resources/Application.md @@ -88,7 +88,7 @@ ###### Install Params Structure -| Field | Type | Description | -| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- | -| scopes | array of strings | the [scopes](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) to add the application to the server with | -| permissions | string | the [permissions](#DOCS_TOPICS_PERMISSIONS) to request for the bot role | +| Field | Type | Description | +| ----------- | ---------------- | ----------------------------------------------------------------------------------------- | +| scopes | array of strings | the [scopes](#DOCS_TOPICS_OAUTH2/oauth2-scopes) to add the application to the server with | +| permissions | string | the [permissions](#DOCS_TOPICS_PERMISSIONS) to request for the bot role | diff --git a/docs/topics/OAuth2.md b/docs/topics/OAuth2.md index eb65a79727..7788d4fd26 100644 --- a/docs/topics/OAuth2.md +++ b/docs/topics/OAuth2.md @@ -17,42 +17,72 @@ The first step in implementing OAuth2 is [registering a developer application](# > warn > In accordance with the relevant RFCs, the token and token revocation URLs will **only** accept a content type of `application/x-www-form-urlencoded`. JSON content is not permitted and will return an error. -###### OAuth2 Scopes +##### OAuth2 Scopes -These are a list of all the OAuth2 scopes that Discord supports. Some scopes require approval from Discord to use. Requesting them from a user without approval from Discord may cause errors or undocumented behavior in the OAuth2 flow. +These are a list of all the OAuth2 scopes that Discord supports. Full access to restricted and private scopes is only granted to applications made by Discord and companies that Discord works with. There is no public application process for these scopes. Requesting them from a user without approval from Discord may cause errors or undocumented behavior in the OAuth2 flow. + +> info +> `guilds.join` and `bot` require you to have a bot account linked to your application. Also, in order to add a user to a guild, your bot has to already belong to that guild. + +###### Public User Scopes + +Users can authorize these scopes using the normal OAuth2 process. + +| Name | Description | +| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| applications.builds.read | allows your app to read build data for a user's applications | +| applications.commands.permissions.update | allows your app to update [permissions for its commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/permissions) in a guild a user has permissions to | +| applications.entitlements | allows your app to read [entitlements](#DOCS_GAME_SDK_STORE/http-apis) for a user's applications | +| applications.store.update | allows your app to read and update store data ([SKUs](#DOCS_GAME_SDK_STORE/http-apis), store listings, [achievements](#DOCS_GAME_SDK_ACHIEVEMENTS/the-api-way), etc.) for a user's applications | +| connections | allows [/users/@me/connections](#DOCS_RESOURCES_USER/get-user-connections) to return linked third-party accounts | +| email | enables [/users/@me](#DOCS_RESOURCES_USER/get-current-user) to return an `email` | +| gdm.join | allows your app to [join users to a group dm](#DOCS_RESOURCES_CHANNEL/group-dm-add-recipient) | +| guilds | allows [/users/@me/guilds](#DOCS_RESOURCES_USER/get-current-user-guilds) to return basic information about all of a user's guilds | +| guilds.join | allows [/guilds/{guild.id}/members/{user.id}](#DOCS_RESOURCES_GUILD/add-guild-member) to be used for joining users to a guild | +| guilds.members.read | allows [/users/@me/guilds/{guild.id}/member](#DOCS_RESOURCES_USER/get-current-user-guild-member) to return a user's member information in a guild | +| identify | allows [/users/@me](#DOCS_RESOURCES_USER/get-current-user) without `email` | +| messages.read | for local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates) | +| rpc.notifications.read | for local rpc server access, this allows you to receive notifications pushed out to the user | + +###### Guild Scopes + +Applications can be added to a guild with these scopes by members with the Manage Server permission, creating an [integration](#DOCS_RESOURCES_GUILD/integration-object). + +| Name | Description | +| ---------------------------------------- | --------------------------------------------------------------------------------------------------- | +| applications.commands | allows your app to use [commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/) in a guild | +| bot | for oauth2 bots, this puts the bot in the user's selected guild by default | +| webhook.incoming | this generates a webhook that is returned in the oauth token response for authorization code grants | + +###### Other Scopes | Name | Description | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| activities.read | allows your app to fetch data from a user's "Now Playing/Recently Played" list - requires Discord approval | -| activities.write | allows your app to update a user's activity - requires Discord approval (NOT REQUIRED FOR [GAMESDK ACTIVITY MANAGER](#DOCS_GAME_SDK_ACTIVITIES/)) | -| applications.builds.read | allows your app to read build data for a user's applications | -| applications.builds.upload | allows your app to upload/update builds for a user's applications - requires Discord approval | -| applications.commands | allows your app to use [commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/) in a guild | | applications.commands.update | allows your app to update its [commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/) using a Bearer token - [client credentials grant](#DOCS_TOPICS_OAUTH2/client-credentials-grant) only | -| applications.commands.permissions.update | allows your app to update [permissions for its commands](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/permissions) in a guild a user has permissions to | -| applications.entitlements | allows your app to read entitlements for a user's applications | -| applications.store.update | allows your app to read and update store data (SKUs, store listings, achievements, etc.) for a user's applications | -| bot | for oauth2 bots, this puts the bot in the user's selected guild by default | -| connections | allows [/users/@me/connections](#DOCS_RESOURCES_USER/get-user-connections) to return linked third-party accounts | -| dm_channels.read | allows your app to see information about the user's DMs and group DMs - requires Discord approval | -| email | enables [/users/@me](#DOCS_RESOURCES_USER/get-current-user) to return an `email` | -| gdm.join | allows your app to [join users to a group dm](#DOCS_RESOURCES_CHANNEL/group-dm-add-recipient) | -| guilds | allows [/users/@me/guilds](#DOCS_RESOURCES_USER/get-current-user-guilds) to return basic information about all of a user's guilds | -| guilds.join | allows [/guilds/{guild.id}/members/{user.id}](#DOCS_RESOURCES_GUILD/add-guild-member) to be used for joining users to a guild | -| guilds.members.read | allows [/users/@me/guilds/{guild.id}/member](#DOCS_RESOURCES_USER/get-current-user-guild-member) to return a user's member information in a guild | -| identify | allows [/users/@me](#DOCS_RESOURCES_USER/get-current-user) without `email` | -| messages.read | for local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates) | -| relationships.read | allows your app to know a user's friends and implicit relationships - requires Discord approval | -| rpc | for local rpc server access, this allows you to control a user's local Discord client - requires Discord approval | -| rpc.activities.write | for local rpc server access, this allows you to update a user's activity - requires Discord approval | -| rpc.notifications.read | for local rpc server access, this allows you to receive notifications pushed out to the user - requires Discord approval | -| rpc.voice.read | for local rpc server access, this allows you to read a user's voice settings and listen for voice events - requires Discord approval | -| rpc.voice.write | for local rpc server access, this allows you to update a user's voice settings - requires Discord approval | -| voice | allows your app to connect to voice on user's behalf and see all the voice members - requires Discord approval | -| webhook.incoming | this generates a webhook that is returned in the oauth token response for authorization code grants | -> info -> `guilds.join` and `bot` require you to have a bot account linked to your application. Also, in order to add a user to a guild, your bot has to already belong to that guild. +###### Restricted User Scopes + +These scopes can be publicly used for application owners and testers. Certain approved apps can use these for all users. + +| Name | Description | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| rpc | for local rpc server access, this allows you to control a user's local Discord client | +| rpc.activities.write | for local rpc server access, this allows you to update a user's activity | +| rpc.voice.read | for local rpc server access, this allows you to read a user's voice settings and listen for voice events | +| rpc.voice.write | for local rpc server access, this allows you to update a user's voice settings | + +###### Private User Scopes + +These scopes can only be used by certain approved apps. + +| Name | Description | +| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| activities.read | allows your app to fetch data from a user's "Now Playing/Recently Played" list | +| activities.write | allows your app to update a user's activity (NOT REQUIRED FOR [GAMESDK ACTIVITY MANAGER](#DOCS_GAME_SDK_ACTIVITIES/)) | +| applications.builds.upload | allows your app to upload/update builds for a user's applications | +| dm_channels.read | allows your app to see information about the user's DMs and group DMs | +| relationships.read | allows your app to know a user's friends and implicit relationships | +| voice | allows your app to connect to voice on user's behalf and see all the voice members | ## State and Security @@ -72,7 +102,7 @@ The authorization code grant is what most developers will recognize as "standard https://discord.com/api/oauth2/authorize?response_type=code&client_id=157730590492196864&scope=identify%20guilds.join&state=15773059ghq9183habn&redirect_uri=https%3A%2F%2Fnicememe.website&prompt=consent ``` -`client_id` is your application's `client_id`. `scope` is a list of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) separated by url encoded spaces (`%20`). `redirect_uri` is whatever URL you registered when creating your application, url-encoded. `state` is the unique string mentioned in [State and Security](#DOCS_TOPICS_OAUTH2/state-and-security). +`client_id` is your application's `client_id`. `scope` is a list of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/oauth2-scopes) separated by url encoded spaces (`%20`). `redirect_uri` is whatever URL you registered when creating your application, url-encoded. `state` is the unique string mentioned in [State and Security](#DOCS_TOPICS_OAUTH2/state-and-security). When someone navigates to this URL, they will be prompted to authorize your application for the requested scopes. On acceptance, they will be redirected to your `redirect_uri`, which will contain an additional querystring parameter, `code`. `state` will also be returned if previously sent, and should be validated at this point. @@ -190,7 +220,7 @@ There are tradeoffs in using the implicit grant flow. It is both quicker and eas The client credential flow is a quick and easy way for bot developers to get their own bearer tokens for testing purposes. By making a `POST` request to the [token URL](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-urls) with a grant type of `client_credentials`, using Basic authentication with your client id as the username and your client secret as the password, you will be returned an access token for the bot owner. Therefore, always be super-extra-very-we-are-not-kidding-like-really-be-secure-make-sure-your-info-is-not-in-your-source-code careful with your `client_id` and `client_secret`. We don't take kindly to imposters around these parts. -You can specify scopes with the `scope` parameter, which is a list of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) separated by spaces: +You can specify scopes with the `scope` parameter, which is a list of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/oauth2-scopes) separated by spaces: > info > Team applications are limited to the `identify` and `applications.commands.update` scope, because teams are not bound to a specific user. diff --git a/docs/topics/RPC.md b/docs/topics/RPC.md index d61d82984b..bad8fabccd 100644 --- a/docs/topics/RPC.md +++ b/docs/topics/RPC.md @@ -150,12 +150,12 @@ We also have an RPC token system to bypass the user authorization modal. This is ###### Authorize Argument Structure -| Field | Type | Description | -| --------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| scopes | array of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) | scopes to authorize | -| client_id | string | OAuth2 application id | -| rpc_token | string | one-time use RPC token | -| username | string | username to create a guest account with if the user does not have Discord | +| Field | Type | Description | +| --------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- | +| scopes | array of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/oauth2-scopes) | scopes to authorize | +| client_id | string | OAuth2 application id | +| rpc_token | string | one-time use RPC token | +| username | string | username to create a guest account with if the user does not have Discord | ###### Authorize Response Structure @@ -203,7 +203,7 @@ Used to authenticate an existing client with your app. | Field | Type | Description | | ----------- | --------------------------------------------------------------------------------------- | ------------------------------- | | user | partial [user](#DOCS_RESOURCES_USER/user-object) object | the authed user | -| scopes | array of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) | authorized scopes | +| scopes | array of [OAuth2 scopes](#DOCS_TOPICS_OAUTH2/oauth2-scopes) | authorized scopes | | expires | date | expiration date of OAuth2 token | | application | [OAuth2 application](#DOCS_TOPICS_RPC/authenticate-oauth2-application-structure) object | application the user authorized | @@ -1469,7 +1469,7 @@ Dispatches message objects, with the exception of deletions, which only contains #### NOTIFICATION_CREATE -No arguments. This event requires the `rpc.notifications.read` [OAuth2 scope](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes). +No arguments. This event requires the `rpc.notifications.read` [OAuth2 scope](#DOCS_TOPICS_OAUTH2/oauth2-scopes). ###### Notification Create Dispatch Data Structure