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.
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_STOREDAsk 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
| Scope | What it allows |
|---|---|
identify | Read the user object (ID, username, avatar) through /users/@me. Does not include the email. |
email | Adds the user's email to /users/@me. |
guilds | List basic info about the servers the user is in. |
guilds.join | Lets your bot add the user to a server it is in. |
guilds.members.read | Read the user's member info (nickname, roles) in a server. |
connections | List the third-party accounts the user has linked. |
bot | Adds your bot to the server the user picks. Includes applications.commands. |
applications.commands | Lets your app register slash commands in a server. |
applications.commands.permissions.update | Update command permissions in servers where the user has the rights. |
role_connections.write | Update the user's linked role connection and metadata. Not usable with the implicit grant. |
webhook.incoming | Creates a webhook in a channel the user picks and returns it in the token response. |
gdm.join | Add the user to a group DM. |
applications.entitlements | Read 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 building | Scopes |
|---|---|
| "Login with Discord" on a website | identify email |
| A bot dashboard that lists the user's servers | identify guilds |
| Member restore or verification | identify guilds.join |
| Role checks based on a member's roles | identify guilds.members.read |
| Adding a bot with slash commands | bot (plus permissions in the URL) |
| Linked Roles | identify 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.
| Scope | For |
|---|---|
dm_channels.read | See the user's DMs and group DMs |
identify.premium | Read the user's Nitro type |
voice | Connect to voice and see voice members |
rpc, rpc.activities.write, rpc.notifications.read, rpc.voice.read, rpc.voice.write | Control or read the user's local Discord client |
applications.builds.upload | Upload builds for the user's apps |
activities.read, activities.write | Not available to apps at all |
relationships.read | Friends 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_typeonly matters withapplications.commands. Use0for a server install and1for a user install, and your app must support that type in the portal.prompt=noneskips the consent screen for a user who already approved the same scopes, except forbotandwebhook.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
identifyandapplications.commands.updatethis 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