Unmerging Provisional Accounts
The link between a Discord account and a provisional account can be severed in four ways:- The user can unmerge their account from the Discord client
- A developer can unmerge the account using the unmerge endpoint on the Discord API
- A developer can use the SDK helper method for public clients
- Discord can sever the link automatically when the user’s Discord account is banned — see Ban-Driven Unmerge below
How Unmerging Works
Every unmerge — whether developer-initiated, user-initiated, or ban-driven — invalidates the user’s tokens and creates a fresh provisional account for the same external identity.Unmerging Provisional Accounts Server-Side
A developer can unmerge a user’s account by sending a request to the unmerge endpoint on the Discord API. The endpoint and identifier you use depend on how the provisional account was created.If you have a server backend, you’ll want to use the server-to-server unmerge endpoint rather than the SDK helper method to maintain better security and control over the unmerge process.
Unmerging with Bot Token Endpoint
If you created the provisional account with the Bot Token Endpoint, you can unmerge accounts without an external auth token — identify the account by the sameexternal_user_id you used to create it.
Unmerging with External Credentials
If you created the provisional account through External Credentials Exchange (OIDC, Steam, EOS, and so on), send the sameexternal_auth_type and external_auth_token you used to create it to the unmerge endpoint.
Unmerging Provisional Accounts for Public Clients
The quickest way to unmerge accounts is to leverage theClient::UnmergeIntoProvisionalAccount method,
which will handle the entire process for you. This method is designed for public clients that don’t have a backend server.
Important Notes:
- This function only works for public clients (applications without backend servers)
- You’ll need to enable “Public Client” on your Discord application’s OAuth2 tab in the Discord developer portal
- After unmerging, you should use
Client::GetProvisionalTokento get a new provisional token for the newly created provisional account
Out-of-Band Unmerge
The link can also be severed without your code calling any unmerge endpoint:- User-initiated: the user removes your app from their Discord
User Settings -> Authorized Appspage. The result is a standard unmerge — the user can re-link freely later. - Ban-driven: when the user’s Discord account is banned by Discord, the link is severed automatically. This is mechanically an unmerge, but with additional lifecycle consequences — see Ban-Driven Unmerge below.
APPLICATION_DEAUTHORIZED webhook fires and stored tokens are invalidated. See Out-of-Band Revocation in the Account Linking guide for the details and recommended recovery path.
These paths don’t require any code changes from you, but we recommend providing an in-app unmerge option through one of the methods above for a better user experience.
Ban-Driven Unmerge
When a player’s Discord account is banned (temporarily or permanently), Discord performs an unmerge automatically. Two things happen:- OAuth2 tokens are deleted immediately — producing the same
APPLICATION_DEAUTHORIZEDwebhook andinvalid_grant-on-refresh signals as any out-of-band revocation. There is no grace period. - A new provisional account is created for the same external identity. Standard unmerge data migration applies — username, friends list, lobbies, and so on are preserved — so the player retains their in-game social graph even though their Discord identity is gone. The new provisional account is created in a restricted state.
- It cannot be merged into a different Discord account. Any merge attempt via
/oauth2/tokenwithexternal_auth_tokenwill fail with error530017“Merge source user is banned”. - For a temporary ban, the restriction lifts automatically when the ban expires, and the provisional account can then be merged again.
- For a permanent ban, the restriction stays in place indefinitely.
There is no API to look up whether a player’s Discord account is currently banned. In practice, the combination of
APPLICATION_DEAUTHORIZED and/or invalid_grant-on-refresh is the signal you should fall
back to the provisional account flow.Data Migration During Unmerging
This is the reverse of merging, and the two are not symmetric. Merging moves the provisional account’s data onto the existing full Discord account, so DM history is preserved. Unmerging instead creates a brand-new provisional account, and DM history is not carried over to it.
- ✅ Username: Global name is copied to the new provisional account
- ✅ In-game friends: All copied to the new provisional account
- ✅ Discord friends who use this application: Copied to the provisional account
- ✅ Blockers: Accounts that blocked the original Discord account are preserved
- ✅ Lobbies: Active lobby memberships for the application are transferred
- ❌ Discord friends who don’t use this application: Not transferred
- ❌ DM message history: Not moved to provisional accounts
Provisional accounts can have Discord friends, but can only message these friends when actively playing the game.
Unmerge Request Failures
You may receive an unmerge specific error code while attempting this operation:Next Steps
Merging Accounts
Merge a provisional account into a full Discord account.
Designing for Provisional Accounts
Design guidelines for implementing provisional accounts in your game.
Account Linking from Your Game
The standard OAuth2 flow for players who already have a Discord account.
#social-sdk-dev-help channel for support from the community.
If you encounter a bug while working with the Social SDK, please report it here: https://dis.gd/social-sdk-bug-report