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

Bots within the Discord API are a separate type of users that are owned by applications (which are owned by users), and authenticate to the system using a token rather than a username and password. Anybody wishing to create a public bot must use a bot account and the OAuth2 API. Accounts violating this and using normal user accounts for public bots will be suspended and forced to use a bot account for their bot. Bot accounts have some differences and limitations to normal accounts, namely:
  1. Bots cannot utilize the friends list feature.
  2. Bots cannot accept invites.
  3. Bots are not limited to a maximum of 100 guilds.
  4. Bots have a per-channel and a global rate limit.

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
https://discordapp.com/api/oauth2/authorizeBase authorization URL
https://discordapp.com/api/oauth2/tokenToken URL
https://discordapp.com/api/oauth2/revokeRevocation URL
Discord also implements refresh tokens, which can be passed to the token URL for valid authentication tokens.


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
botfor oauth2 bots, this puts the bot in the user's selected guild by default
connectionsallows [email protected]/connections to return linked Twitch and YouTube 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 a user's 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


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):
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):
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
idsnowflakethe id of the app
namestringthe name of the app
iconstring?the icon hash of the app
descriptionstring?the 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_requires_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_requires_code_grant": false,
    "owner": {
        "username": "i own a bot",
        "discriminator": "1738",
        "id": "172150183260323840",
        "avatar": null