The Discord OAuth2 scopes RestoreCord requests

Every RestoreCord verification is an ordinary Discord OAuth2 authorization-code flow. The scopes on the consent screen come from the server's settings, and each one exists for a specific reason.

Short answer

identify is always requested. guilds.join is added when the server enables its join scope, which is what makes later member pulls possible. guilds is added for server-membership firewall rules, and email when the server requires email addresses.

The authorize request

When a member clicks Verify, the page sends them to Discord with a URL like the one below. The redirect returns to the server's verification domain: restorecord.com by default, or the owner's custom domain when the bot has one.

Authorize URL (line breaks added)text
https://discord.com/oauth2/authorize
  ?client_id=<your bot's application ID>
  &redirect_uri=https://<verify domain>/api/callback
  &response_type=code
  &scope=identify+guilds.join          # + guilds, + email when enabled
  &state=<server ID>.<link code>       # link code is optional
  &prompt=none                         # only when guilds and email are off

Each scope, and when it appears

ScopeGives RestoreCordRequested when
identifyUser ID, username and avatarAlways
guilds.joinPermission for the bot to add the user to a serverThe server's join scope is enabled
guildsThe list of servers the user is inThe server views memberships, for example to block raid sources
emailThe email address on the accountThe server saves or requires emails

Because the scope list is built per server, a member joining a minimal server sees a short consent screen, while a server that blocks members of hostile servers will also ask to see their server list. Nothing is requested that the owner hasn't switched on.

Why some members skip the consent screen

If the server requests only identify and guilds.join, RestoreCord appends prompt=none. Discord then skips the consent screen for anyone who has already authorised the same application with those scopes, so returning members verify in one click. Adding guilds or email drops that parameter and the screen always appears.

What travels in state

The state value is the Discord server ID, optionally followed by a dot and a tracking-link code. On the callback, RestoreCord reads it to know which server the verification belongs to and which link brought the member in. No cookies are needed for attribution.

Tokens, refresh and revocation

The callback exchanges Discord's authorisation code for an access token and a refresh token and stores them against the member's record for that server. Access tokens expire quickly, which is why the refresh token matters: it lets RestoreCord obtain a fresh access token months later, when the owner actually needs to pull members.

Members can end this at any time under User Settings, Authorized Apps in Discord. Discord sends the application a deauthorisation event, RestoreCord marks the member as deauthorised for the servers using that bot and records the event in member analytics. From then on they can't be pulled until they verify again.

OAuth2 tokens are not Discord login tokens. They can only do what the granted scopes allow, and the member's password is never involved.

Choosing scopes as an owner

Every extra scope adds a line to the consent screen, and every line is a reason for a cautious member to hesitate. A practical rule:

  • Keep guilds.join on. Without it, verified members can't be pulled after a raid or takeover
  • Add guilds only if you actually write server-membership rules, a Business feature
  • Require email only when you have a real use for it, such as email-domain firewall rules
  • Re-test verification from a spare account after changing scopes

See how the browser signal works in alt detection signals, why pulls take time in rate limits, or go back to the pipeline overview.

Three scope sets, side by side

What each combination costs on the consent screen and what it unlocks for your rules.

identify + guilds.join+ guilds+ email
Returning members can skip consent——
Members can be pulled later
Firewall rules on other servers——
Email-domain firewall rules——
Extra line on Discord's screen—

OAuth2 scope questions

Choose exactly what your server asks for

Scopes follow your settings. Turn on only what your verification really needs.