Skip to content
Menu

Discord OAuth2 scopes explained

A scope decides what your access token can do. This page lists the Discord OAuth2 scopes you can use, the ones that need approval, and the combinations that real apps request.

Step 0Before you start: create a free VaultCord account

Do this before you write any code. A free VaultCord account gives you a working verification flow to compare your own against, plus a fallback if your bot goes down.

  • Your own branded bot: 1 on Free, 3 on Premium, unlimited on Plus, online 24/7.
  • Unlimited restorable members on every plan, Free included. Pulls run at one member every 0.98 seconds, on every plan.
  • Developer API to pull members with code (Plus), plus a Resell Members API. Plus is $9.97/mo, or $3.83/mo billed yearly.
  • An MCP server, so Claude or another MCP client can run your account, and the iOS and Android apps.
On this page

How scopes are requested

You put scopes in the scope parameter of the authorize URL, separated by spaces. In a URL the space is written %20. The user sees each scope on Discord's consent screen, and the token you get back only covers what they approved.

authorize URL (line breaks added for reading)
https://discord.com/oauth2/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &scope=identify%20email%20guilds
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &state=RANDOM_STRING_YOU_STORED

Ask for as little as you need. Every extra scope adds a line to the consent screen, and people do read it. If you need more later, send the user through the flow again with the larger set.

Scopes most apps use

ScopeWhat it allows
identifyRead the user object (ID, username, avatar) through /users/@me. Does not include the email.
emailAdds the user's email to /users/@me.
guildsList basic info about the servers the user is in.
guilds.joinLets your bot add the user to a server it is in.
guilds.members.readRead the user's member info (nickname, roles) in a server.
connectionsList the third-party accounts the user has linked.
botAdds your bot to the server the user picks. Includes applications.commands.
applications.commandsLets your app register slash commands in a server.
applications.commands.permissions.updateUpdate command permissions in servers where the user has the rights.
role_connections.writeUpdate the user's linked role connection and metadata. Not usable with the implicit grant.
webhook.incomingCreates a webhook in a channel the user picks and returns it in the token response.
gdm.joinAdd the user to a group DM.
applications.entitlementsRead entitlements for the user's apps.

There are also scopes for specific setups: messages.read reads messages through the local RPC server, applications.builds.read and applications.store.update are for games and store data, and applications.commands.update lets you update commands with a bearer token from the client credentials grant.

Common combinations

You are buildingScopes
"Login with Discord" on a websiteidentify email
A bot dashboard that lists the user's serversidentify guilds
Member restore or verificationidentify guilds.join
Role checks based on a member's rolesidentify guilds.members.read
Adding a bot with slash commandsbot (plus permissions in the URL)
Linked Rolesidentify role_connections.write

For the bot install flow, Discord adds a few more URL parameters: permissions (an integer bitfield), guild_id to preselect a server, and disable_guild_select=true to stop the user changing it. If your URL only has client_id and those optional parameters, Discord uses the default install settings from your Developer Portal.

Scopes that need approval

Discord marks these as needing approval or limited to approved partners. Requesting them without approval can cause errors or undocumented behaviour.

ScopeFor
dm_channels.readSee the user's DMs and group DMs
identify.premiumRead the user's Nitro type
voiceConnect to voice and see voice members
rpc, rpc.activities.write, rpc.notifications.read, rpc.voice.read, rpc.voice.writeControl or read the user's local Discord client
applications.builds.uploadUpload builds for the user's apps
activities.read, activities.writeNot available to apps at all
relationships.readFriends list. Needs Social SDK access

Rules that trip people up

  • The token and revoke endpoints only take form bodies. Send application/x-www-form-urlencoded, not JSON.
  • integration_type only matters with applications.commands. Use 0 for a server install and 1 for a user install, and your app must support that type in the portal.
  • prompt=none skips the consent screen for a user who already approved the same scopes, except for bot and webhook.incoming, which always show it.
  • Client credentials has no user. It gives you a token for your own account. Team-owned apps can only get identify and applications.commands.update this way.
  • Revoking one token revokes the authorization. Every access and refresh token for it stops working.

Redirect URI mismatch is the most common error

If the authorize screen says "Invalid OAuth2 redirect_uri", the scopes are fine; the URL is not. See the redirect URI guide.

What VaultCord asks for

VaultCord's verification flow exists to make member restore possible, so it asks for guilds.join: that is the scope that lets your bot add a verified member back to a server. When the time comes, VaultCord pulls one member every 0.98 seconds, on every plan. Unlimited restorable members on every plan, Free included.

If a member removes the app from their Discord settings, the authorization is gone and so is the ability to add them. Instant deauthorization detection keeps member records in sync. Set up verification in the dashboard, or read the rate limit guide if you are building this yourself.

FAQ

What are Discord OAuth2 scopes?

Scopes are the permissions your app asks a user for on Discord's authorize screen. You list them in the scope parameter, separated by spaces (%20 in the URL), and the access token you get back can only do what those scopes allow.

Which scope gives me the user's email?

email. identify alone returns the user object without the email. Most login integrations ask for identify and email together.

What is the difference between the bot and applications.commands scopes?

bot adds your bot user to the server the user picks. applications.commands lets your app register slash commands there. The bot scope already includes applications.commands.

Does guilds.join need approval?

No. It is not in the list of scopes Discord marks as needing approval. It does need your bot to be in the target server with the Create Instant Invite permission.

Can a team-owned app use any scope with client credentials?

No. With the client credentials grant, apps owned by a team are limited to identify and applications.commands.update.

Last updated on November 19, 2026