OAuth2

OAuth2 enables application developers to build applications that utilize authentication and data from the Discord API. Within the Discord platform, there are two types of oauth2 authentication, "full stack" or "application" auth and bot auth. The former is what is most people will recognize as generic OAuth2, and allows the developer to authenticate and make certain requests on behalf of a user. The latter enables bot creators to have an easy, callback/server-free flow for giving users the ability to add their bot to servers they own.

Bot vs User Accounts

Discord's API provides a seperate type of user account dedicated to automation, called a bot account. Bot accounts can be created through the applications page, and are authenticated using a token (rather than a username and password). Unlike the normal OAuth2 flow, bot accounts have full access to all API routes without using bearer tokens, and can connect to the Real Time Gateway. Automating normal user accounts (generally called "self-bots") outside of the OAuth2/bot API is forbidden, and can result in an account termination if found.Bot accounts have a few differences in comparison to normal user accounts, namely:
  1. Bots are added to servers through the OAuth2 API, and cannot accept normal invites.
  2. Bots cannot have friends, nor be added to or join Group DMs.
  3. Bots do not have a maximum number of Guilds (unlike user accounts, which are limited to 100).
  4. Bots have an entirely separate set of Rate Limits.
Users interested in providing real-time automation to user accounts should consider the RPC API.

Implementing OAuth2

Registering Applications

The first step in implementing OAuth2 is registering a developer application, and retrieving your client ID and client secret. Most people who will be implementing OAuth2 will want to find and utilize a library in the language of their choice. For those implementing OAuth2 from scratch, please see RFC 6749 for details. In the Discord OAuth2 API, it's technically valid to not have a redirect URI for your application, this enables one-sided authentication flows which allow for server-less bot-adding. The URLs for OAuth2 are as follows:
OAuth2 Application URLs
URLDescription
https://discordapp.com/api/oauth2/authorizeBase authorization URL
https://discordapp.com/api/oauth2/tokenToken URL
https://discordapp.com/api/oauth2/token/revokeRevocation URL
Discord also implements refresh tokens, which can be passed to the token URL for valid authentication tokens.

Scopes

Scopes provide access to certain resources of a user's account. Your API client or service should only request scopes it requires for operation.
OAuth2 Scopes
NameDescription
botfor oauth2 bots, this puts the bot in the user's selected guild by default
connectionsallows [email protected]/connections to return linked third-party accounts
emailenables [email protected] to return an email
identifyallows [email protected] without email
guildsallows [email protected]/guilds to return basic information about all of a user's guilds
guilds.joinallows /invites/{invite.id} to be used for joining users to a guild
gdm.joinallows your app to join users to a group dm
messages.readfor local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates)
rpcfor local rpc server access, this allows you to control a user's local Discord client
rpc.apifor local rpc server api access, this allows you to access the API as the local user
rpc.notifications.readfor local rpc server api access, this allows you to receive notifications pushed out to the user
webhook.incomingthis generates a webhook that is returned in the oauth token response for authorization code grants
Unlike the rest of the scopes, guilds.join requires you to have a bot account linked to your application and can only be used to join users to guilds which your bot services.

Bots

Bots within the Discord API are a form of user account that is authenticated without a username or password, and has similar properties and abilities to normal user accounts. Bot accounts enable developers to have a simple portal that allows authenticated users to add third-party bots to servers they own or manage.

Registering Bots

Bots can be registered by clicking the "add bot" button when editing or creating an OAuth2 application.

Two-Factor Authentication Requirement

For bots with elevated permissions (permissions with a * next to them), we enforce two-factor authentication for the owner's account when used on guilds that have server-wide 2FA enabled.

Adding Bots to Guilds

A URL can be generated that redirects authenticated users to the add-bot flow, by using the following format (this utilizes the OAuth2 authentication flow, without a callback URL):
https://discordapp.com/api/oauth2/authorize?client_id=157730590492196864&scope=bot&permissions=0
client_id is your bot application's ID and permissions is an integer following the permissions format.

Adding Webhooks to Channels

A URL can be generated that redirects authenticated users to the add-webhook flow, by using the following format (this utilizes the OAuth2 authentication authorization code flow, which requires a server-side application):
https://discordapp.com/api/oauth2/authorize?client_id=157730590492196864&scope=webhook.incoming&redirect_uri=https%3A%2F%2Fnicememe.website&response_type=code
client_id is your application's ID and redirect_uri is one of your application's URL-encoded redirect URIs.When a user is directed to this URL, they are prompted to select a channel for the webhook to be placed in. Your application will receive an authorization code back in the querystring (as usual with the authorization code grant).When you exchange the authorization code for an access token, the token response will contain the webhook object:
{
    "token_type": "Bearer",
    "access_token": "7r70pJOvarwv1fkPqacZqFOCv39tX2",
    "scope": "webhook.incoming",
    "expires_in": 604800,
    "refresh_token": "TY0U8LP8joJURIhqREL4AuQXcj5DlO",
    "webhook": {
        "name": "test",
        "channel_id": "199737254929760256",
        "token": "DuAt6zzLQpPhaAq0IcnCrDUWWpY9Y07dqkB5ulLkhwpA00ZK7IjLve5AE4ACUZqCUTY8",
        "avatar": "eaa0292a003ceb15264a838a8eff961a",
        "guild_id": "199737254929760256",
        "id": "236380988341485568"
    }
}

Get Current Application Information

GET[email protected]
Returns the bot's OAuth2 application info.
Response Structure
FieldTypeDescription
idsnowflakethe id of the app
namestringthe name of the app
icon?stringthe icon hash of the app
description?stringthe description of the app
rpc_origins?arrayan array of rpc origin url strings, if rpc is enabled
bot_publicbooleanwhen false only app owner can join the app's bot to guilds
bot_require_code_grantbooleanwhen true the app's bot will only join upon completion of the full oauth2 code grant flow
ownerUserpartial user object containing info on the owner of the application
Example Application Information
{
    "description": "Test",
    "icon": null,
    "id": "172150183260323840",
    "name": "Baba O-Riley",
    "bot_public": true,
    "bot_require_code_grant": false,
    "owner": {
        "username": "i own a bot",
        "discriminator": "1738",
        "id": "172150183260323840",
        "avatar": null
    }
}