Skip to main content

Unmerging Provisional Accounts

The link between a Discord account and a provisional account can be severed in four ways:
  1. The user can unmerge their account from the Discord client
  2. A developer can unmerge the account using the unmerge endpoint on the Discord API
  3. A developer can use the SDK helper method for public clients
  4. Discord can sever the link automatically when the user’s Discord account is banned — see Ban-Driven Unmerge below
Unmerging invalidates all access/refresh tokens for the user. They cannot be used again after the unmerge operation completes. Any connected game sessions will be disconnected.
Unmerging does not affect the external identity you used to create the provisional account — your external_user_id (for the Bot Token Endpoint), or your external_auth_token (for OIDC, Steam, EOS, and other credential-exchange providers). After the unmerge completes, you can re-authenticate with that same identity to retrieve the token for the newly created provisional account.

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 same external_user_id you used to create it.
This endpoint can also be useful in cases where the Discord Auth token has been lost to error or data loss, and an unmerge operation is required to migrate to a provisional account before re-linking a Discord account.

Unmerging with External Credentials

If you created the provisional account through External Credentials Exchange (OIDC, Steam, EOS, and so on), send the same external_auth_type and external_auth_token you used to create it to the unmerge endpoint.

Unmerging Provisional Accounts for Public Clients

This method requires enabling Public Client for your app. Most games will not want to ship with this enabled. Learn more
The quickest way to unmerge accounts is to leverage the Client::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::GetProvisionalToken to 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 Apps page. 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.
In both cases your app observes the same auth-side signals — an 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:
  1. OAuth2 tokens are deleted immediately — producing the same APPLICATION_DEAUTHORIZED webhook and invalid_grant-on-refresh signals as any out-of-band revocation. There is no grace period.
  2. 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.
While the new provisional account is restricted:
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.
When a user unmerges their account, a new provisional account is created with a new user ID. The following data is transferred to the new provisional account asynchronously:
  • ✅ 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
The following data is not 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.
Need help? Join the Discord Developers Server and share questions in the #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

Change Log