Skip to content
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

RequirementWhy
User authorized guilds.joinThe access token is what proves the user agreed to be added.
Bot is already a member of the target serverThe bot makes the call, so it must be in the server.
Bot has CREATE_INSTANT_INVITEDiscord requires it for this endpoint.
MANAGE_NICKNAMES, MANAGE_ROLES, MUTE_MEMBERS, DEAFEN_MEMBERSOnly if you also send nick, roles, mute or deaf.
The user's IDGet 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.

authorize URL (line breaks added for reading)
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_STORED

Exchange 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.

exchange.sh
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/callback

Add 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"'"}'

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:

CodeDiscord's messageUsual cause here
50025Invalid OAuth2 access token providedToken expired, revoked, or issued by a different app.
50013You lack permissions to perform that actionBot missing Create Instant Invite, or Manage Roles when sending roles.
40007The user is banned from this guildUnban first, or skip the user.
30001Maximum number of guilds reached (100)The account is at Discord's server limit and has to leave one first.
10004Unknown guildWrong 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 is 604800 seconds (7 days).
  • Refresh with grant_type=refresh_token at the same token URL and store the new pair.
  • Users can remove your app at any time. Discord can send an APPLICATION_DEAUTHORIZED webhook 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 flowWhat VaultCord does
Pull speedOne member every 0.98 seconds, on every plan.
Rate limitsCustom join delay between pulls to reduce Discord rate limits. Proxied requests on every plan.
Revoked tokensInstant deauthorization detection keeps member records in sync.
How many membersUnlimited restorable members on every plan, Free included.
Doing it in codeDeveloper API to pull members with code (Plus), plus a Resell Members API.
Many sourcesPull from multiple servers at once on Plus.
Your own botYour 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

FreePremiumPlus
Monthly$0$4.97$9.97
Billed yearly, per month$0$2.33 (save 53%)$3.83 (save 62%)
Servers15Unlimited
Custom bots13Unlimited
Pull cooldown10h1hNone
Pull speed0.98 s per member on every plan
Restorable membersUnlimited on every plan
Developer APINoNoYes
Multi-server pullNoNoYes

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