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:
| Sent | Saved | Problem |
|---|---|---|
http://example.com/callback | https://example.com/callback | Scheme differs |
https://www.example.com/callback | https://example.com/callback | Host differs |
https://example.com/callback/ | https://example.com/callback | Trailing slash |
http://localhost:5173/callback | http://localhost:3000/callback | Port differs |
https://example.com/auth/callback | https://example.com/callback | Path 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 seehttps://. Set the redirect URI from config instead of building it from the request. - The
client_idbelongs 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")import os
from urllib.parse import urlencode, quote
params = {
"response_type": "code",
"client_id": os.environ["DISCORD_CLIENT_ID"],
"scope": "identify guilds.join",
"redirect_uri": os.environ["DISCORD_REDIRECT_URI"], # exactly as saved in the portal
"state": state,
}
url = "https://discord.com/oauth2/authorize?" + urlencode(params, quote_via=quote)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:
localhostand127.0.0.1are 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
https://example.com/callback
?code=NhhvTDYsFcdgNLnnLijcl7Ku7bEEeee
&state=RANDOM_STRING_YOU_STORED
&iss=https%3A%2F%2Fdiscord.comcode: 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 alwayshttps://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