Menu
Add users to a Discord server with OAuth2 guilds.join
The guilds.join scope lets your app put a user into a server where your bot already is. Here is the full flow, the exact request, the errors you will hit, and how VaultCord does it for you.
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 guilds.join does
guilds.join is an OAuth2 scope. When a user approves it, your application gets an access token that lets it add that user to a server. The adding is done by your bot, not by the user: the bot calls PUT /guilds/{guild.id}/members/{user.id} with its own bot token in the Authorization header and the user's access token in the JSON body.
This is how member restore tools work. People authorize once, usually on a verification page. If the server is raided, nuked or deleted, the owner can put those people into a new server without sending a single invite link.
Bot token and user token must come from the same app
Discord only accepts the request if the bot token belongs to the same application that the user authorized. A token from another app, even one you own, will fail.
Requirements
| Requirement | Why |
|---|---|
User authorized guilds.join | The access token is what proves the user agreed to be added. |
| Bot is already a member of the target server | The bot makes the call, so it must be in the server. |
Bot has CREATE_INSTANT_INVITE | Discord requires it for this endpoint. |
MANAGE_NICKNAMES, MANAGE_ROLES, MUTE_MEMBERS, DEAFEN_MEMBERS | Only if you also send nick, roles, mute or deaf. |
| The user's ID | Get it from GET /users/@me with the user's token, which is why most apps ask for identify too. |
The flow, step by step
Register a redirect URI
In the Developer Portal, open your application, go to OAuth2 and add the exact URL Discord should send users back to. It has to match what you send later character for character. The redirect URI guide covers the usual mistakes.
Send the user to the authorize URL
Ask for identify and guilds.join. Scopes are space separated, so they are joined with %20 in the URL. Always send a state value and check it when the user comes back.
https://discord.com/oauth2/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&scope=identify%20guilds.join
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
&state=RANDOM_STRING_YOU_STOREDExchange the code for tokens
Discord redirects to your URI with code and state (and, since October 2026, an iss parameter set to https://discord.com). Trade the code at the token URL. That endpoint only accepts application/x-www-form-urlencoded bodies, and the redirect_uri must be the same one you used in step 2.
curl -X POST https://discord.com/api/oauth2/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=authorization_code \
-d code="$CODE" \
--data-urlencode redirect_uri=https://example.com/callbackAdd the user with your bot
Call Add Guild Member with the bot token. Send a User-Agent in the DiscordBot (url, version) format, since requests without a valid one can be blocked.
curl -X PUT "https://discord.com/api/v10/guilds/$GUILD_ID/members/$USER_ID" \
-H "Authorization: Bot $BOT_TOKEN" \
-H "Content-Type: application/json" \
-H "User-Agent: DiscordBot (https://example.com, 1.0)" \
-d '{"access_token": "'"$ACCESS_TOKEN"'"}'const res = await fetch(
`https://discord.com/api/v10/guilds/${guildId}/members/${userId}`,
{
method: "PUT",
headers: {
Authorization: `Bot ${process.env.BOT_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ access_token: accessToken }),
}
)
if (res.status === 201) console.log("added", await res.json())
else if (res.status === 204) console.log("already a member")
else console.error(res.status, await res.json())import os
import requests
r = requests.put(
f"https://discord.com/api/v10/guilds/{guild_id}/members/{user_id}",
headers={"Authorization": f"Bot {os.environ['BOT_TOKEN']}"},
json={"access_token": access_token},
)
if r.status_code == 201:
print("added", r.json())
elif r.status_code == 204:
print("already a member")
else:
print(r.status_code, r.json())Responses and errors
A 201 Created comes back with the new guild member object, and the server receives a Guild Member Add event. If the user is already in the server you get 204 No Content and nothing changes. In servers with Membership Screening, new members are added as pending and can't talk until they complete screening.
When it fails, the JSON body carries a numeric code. These are the ones you will see most with this endpoint:
| Code | Discord's message | Usual cause here |
|---|---|---|
50025 | Invalid OAuth2 access token provided | Token expired, revoked, or issued by a different app. |
50013 | You lack permissions to perform that action | Bot missing Create Instant Invite, or Manage Roles when sending roles. |
40007 | The user is banned from this guild | Unban first, or skip the user. |
30001 | Maximum number of guilds reached (100) | The account is at Discord's server limit and has to leave one first. |
10004 | Unknown guild | Wrong guild ID, or the bot is not in that server. |
Adding many members in a row is where most people hit 429 Too Many Requests. Read the rate limit guide before you loop over a member list.
Keeping tokens valid
- The token response includes
expires_in. Discord's example value is604800seconds (7 days). - Refresh with
grant_type=refresh_tokenat the same token URL and store the new pair. - Users can remove your app at any time. Discord can send an
APPLICATION_DEAUTHORIZEDwebhook event to your Webhook Events URL so you can mark them as gone instead of finding out on the next failed PUT. - Revoking any token revokes every access and refresh token for that authorization, so only revoke when the user asked to unlink.
How VaultCord runs it
If you would rather not run the OAuth2 app, token storage and retry queue yourself, VaultCord does all of it. Members verify through your bot's verification page (Cloudflare Turnstile and hCaptcha), which records their authorization. When you need them, you pull them into any server your bot is in from the dashboard, the apps, or a slash command.
| Part of the flow | What VaultCord does |
|---|---|
| Pull speed | One member every 0.98 seconds, on every plan. |
| Rate limits | Custom join delay between pulls to reduce Discord rate limits. Proxied requests on every plan. |
| Revoked tokens | Instant deauthorization detection keeps member records in sync. |
| How many members | Unlimited restorable members on every plan, Free included. |
| Doing it in code | Developer API to pull members with code (Plus), plus a Resell Members API. |
| Many sources | Pull from multiple servers at once on Plus. |
| Your own bot | Your own branded bot: 1 on Free, 3 on Premium, unlimited on Plus, online 24/7. |
| Commands | /verify-embed, /pull, /info, /backup, /massrole, /unrole |
API reference
VaultCord's own endpoints are documented at docs.vaultcord.com. Create a key in the dashboard once you are on Plus.
Plans
| Free | Premium | Plus | |
|---|---|---|---|
| Monthly | $0 | $4.97 | $9.97 |
| Billed yearly, per month | $0 | $2.33 (save 53%) | $3.83 (save 62%) |
| Servers | 1 | 5 | Unlimited |
| Custom bots | 1 | 3 | Unlimited |
| Pull cooldown | 10h | 1h | None |
| Pull speed | 0.98 s per member on every plan | ||
| Restorable members | Unlimited on every plan | ||
| Developer API | No | No | Yes |
| Multi-server pull | No | No | Yes |
Open the dashboard to start on Free. You can move to Plus when you want the API.
FAQ
What does the Discord OAuth2 guilds.join scope do?
It lets your application add the user who authorized it to a server. Your bot makes the request with PUT /guilds/{guild.id}/members/{user.id}, sending the user's access token in the body. The bot has to be in that server already and needs the Create Instant Invite permission.
Can I join a Discord guild by ID?
A user can't type a server ID into Discord to join it; they need an invite. An application can add a user to a server by its ID with guilds.join, but only after that user authorized the app and only in servers where the app's own bot is a member.
Why does Add Guild Member return an error instead of 201?
The common ones: 50025 means the access token is invalid, expired or revoked. 50013 means the bot lacks a permission (Create Instant Invite, or Manage Roles if you pass roles). 40007 means the user is banned from that server. 30001 means the maximum number of guilds (100) was reached.
How long does a guilds.join access token last?
The token response tells you in expires_in. Discord's documented example is 604800 seconds, which is 7 days. Store the refresh_token and trade it for a new access token with grant_type=refresh_token before you need to add the user again.
Does guilds.join need approval from Discord?
No. In Discord's OAuth2 scope list, guilds.join is not one of the scopes marked as needing approval. Scopes like rpc, voice and dm_channels.read are the ones that do.
How does VaultCord use guilds.join?
Members authorize your VaultCord bot when they verify. When you need them back, VaultCord pulls them into the server you choose, one member every 0.98 seconds, on every plan, and detects deauthorizations so your member count stays honest.
Is there a VaultCord API for pulling members?
Yes. Developer API to pull members with code (Plus), plus a Resell Members API. Slash commands such as /pull work on every plan.
Last updated on November 19, 2026