Skip to content
Menu

Discord OAuth2 redirect URI setup and the invalid redirect_uri error

Discord compares your redirect_uri to the list in your app settings, character for character. Here is how to set it up, why the error appears, and how to make localhost work.

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

What the redirect URI is

After a user approves your app on Discord's authorize screen, Discord sends their browser back to your site with a one-time code. The address it sends them to is the redirect URI. You pass it as redirect_uri in the authorize URL, URL-encoded, and it has to be one of the URLs you registered for the application.

That rule exists so nobody can build an authorize link for your app that sends your users' codes to their own server.

Adding one in the portal

Open your app

Go to the Discord Developer Portal, pick your application and open the OAuth2 page.

Add the URL under Redirects

Paste the full callback URL, for example https://example.com/api/auth/discord/callback. Add one entry per environment: production, staging and local development each get their own line.

Save the changes

Save before you test. A redirect you typed but never saved does not count, and it is an easy one to miss when you are switching between tabs.

Fixing Invalid OAuth2 redirect_uri

This message on the authorize screen means Discord could not find your redirect_uri in the saved list. Compare the value your app sends (decode it from the browser address bar) with the portal entry, line by line:

SentSavedProblem
http://example.com/callbackhttps://example.com/callbackScheme differs
https://www.example.com/callbackhttps://example.com/callbackHost differs
https://example.com/callback/https://example.com/callbackTrailing slash
http://localhost:5173/callbackhttp://localhost:3000/callbackPort differs
https://example.com/auth/callbackhttps://example.com/callbackPath differs

Other causes worth checking:

  • The value is not URL-encoded, so part of it is read as a separate parameter.
  • A reverse proxy or framework builds the callback from the internal host, so the app sends http:// or an internal hostname while users see https://. Set the redirect URI from config instead of building it from the request.
  • The client_id belongs to a different application than the one you edited.

Build the URL with an encoder instead of string concatenation:

const params = new URLSearchParams({
  response_type: "code",
  client_id: process.env.DISCORD_CLIENT_ID,
  scope: "identify guilds.join",
  redirect_uri: process.env.DISCORD_REDIRECT_URI, // exactly as saved in the portal
  state,
})

// URLSearchParams encodes the redirect URI and turns the space in scope into +.
// Discord's docs write spaces as %20, so swap them to match.
const url = "https://discord.com/oauth2/authorize?" + params.toString().replace(/\+/g, "%20")

Redirect URI on localhost

Local development works the same way. Save the exact local URL, such as http://localhost:3000/api/auth/discord/callback, next to your production one. Then make sure the app really sends that value while it runs locally:

  • localhost and 127.0.0.1 are different strings. Pick one and use it everywhere.
  • Dev servers change ports when the default one is busy. If yours moved from 3000 to 3001, the redirect no longer matches.
  • Keep the redirect in an environment variable per environment, so production never sends the localhost URL.

The second place it must match

When you exchange the code at https://discord.com/api/oauth2/token, you send redirect_uri again, and it has to be the same value you used in the authorize URL. The endpoint only accepts application/x-www-form-urlencoded bodies. A JSON body or a different redirect makes the exchange fail even though the redirect itself worked.

Bot installs don't need a redirect

The scope=bot flow is callback-less. If you combine bot with other scopes and leave out redirect_uri, Discord redirects to the first URI in your saved list. Passing one overrides that.

What arrives at your callback

callback URL
https://example.com/callback
  ?code=NhhvTDYsFcdgNLnnLijcl7Ku7bEEeee
  &state=RANDOM_STRING_YOU_STORED
  &iss=https%3A%2F%2Fdiscord.com
  • code: trade it for tokens once.
  • state: compare it with the value you stored for this session before doing anything else.
  • iss: added in October 2026 and always https://discord.com. If your app supports more than one login provider, check it before exchanging the code.

If you are building member restore, the scope to request is guilds.join; the guilds.join guide continues from here, and OAuth2 scopes lists the rest.

Skipping all of this

If the only reason you are setting up OAuth2 is to verify members and pull them back after a raid, VaultCord already runs the authorize page, the token exchange and the storage. You bring the bot. Your own branded bot: 1 on Free, 3 on Premium, unlimited on Plus, online 24/7. Custom verification domain on Premium and Plus. Start in the dashboard.

FAQ

What does Invalid OAuth2 redirect_uri mean on Discord?

The redirect_uri in your authorize URL is not one of the redirects saved for your application. Discord compares them exactly, so a different scheme (http vs https), host, port, path or trailing slash is enough to trigger it.

Can I use localhost as a Discord OAuth2 redirect URI?

Yes, as long as the exact URL you send is saved in the portal, including the port and path. localhost and 127.0.0.1 are different strings, so save the one your app actually uses.

Where do I add a redirect URI for my Discord app?

In the Developer Portal, open your application, go to the OAuth2 page, add the URL under Redirects and save the changes.

Why does the code exchange fail after the redirect worked?

The token request must send the same redirect_uri you used in the authorize URL. If they differ, or if the code was already used, the exchange fails.

Do I need a redirect URI to add a bot to a server?

No. The bot authorization flow (scope=bot) is callback-less and needs no redirect_uri. If you add other scopes and leave redirect_uri out, Discord sends the user to the first redirect in your list.

Last updated on November 19, 2026