tweaks

spenhand · spenhand · commit 10a377851ef9 · 2025-09-12T16:37:32.000-04:00
diff --git a/docs/discord-social-sdk/development-guides/using-provisional-accounts.mdx b/docs/discord-social-sdk/development-guides/using-provisional-accounts.mdx
@@ -67,17 +67,22 @@ For existing Discord users who have added a provisional account as a game friend
 
 ---
 
-## Choosing an Authentication Method
+## Getting Set Up
+### Choosing an Authentication Method
 
-Discord offers a number of authentication methods tailored to different games:
+Discord offers a number of authentication methods, the one you use depends on how you game and account system is set up:
 
-1. Use the [**Bot Token Endpoint**](/docs/discord-social-sdk/development-guides/using-provisional-acounts#bot-token-endpoint#) if your game has an account system which uniquely identifies users. This is the recommended approach when possible.
-2. Use the [**External Credentials Exchange Endpoint**](/docs/discord-social-sdk/development-guides/using-provisional-acounts#external-credentials-exchange-endpoint) if you have an existing OIDC provider, or do not have an account system.
-3. Use the [**Client Side Token Exchange Method**](/docs/discord-social-sdk/development-guides/using-provisional-acounts#provisional-account-authentication-for-public-clients) if you are using a Public Client.
+1. Use the [Bot Token Endpoint](/docs/discord-social-sdk/development-guides/using-provisional-accounts#bot-token-endpoint#) if your game has an account system which uniquely identifies users. This is the recommended approach when possible.
+2. Use the [External Credentials Exchange Endpoint](/docs/discord-social-sdk/development-guides/using-provisional-accounts#external-credentials-exchange-endpoint) if you have an existing OIDC provider, or do not have an account system.
+3. Use the [Client Side Token Exchange Method](/docs/discord-social-sdk/development-guides/using-provisional-accounts#provisional-account-authentication-for-public-clients) if you are using a Public Client.
 
-If you are using the **External Credentials Exchange Endpoint** or **Client Side Token Exchange Method**, you must [configure you identity provider](/docs/discord-social-sdk/development-guides/using-provisional-acounts#configuring-your-identity-provider) before proceeding.
+If you are using (2) or (3), you must configure you identity provider before proceeding.
 
-## Configuring Your Identity Provider
+### Configuring Your Identity Provider
+
+:::warn
+If you are using the bot token endpoint, no configuration is required.
+:::
 
 Open the Discord app for your game in the [Developer Portal](https://discord.com/developers/applications). Find the `External Auth` page under the `Discord Social SDK` section in the sidebar.
 
@@ -90,9 +95,7 @@ We currently support the following provider types:
 - Epic Online Services (EOS)
 - Unity
 
-If you are using the bot token endpoint, no configuration is required.
-
-Which are represented in Discord's systems by the following types:
+Providers are represented in Discord's systems by the following types:
 
 #### External Auth Types
 
@@ -115,7 +118,7 @@ You provide external authentication and uniquely identifies the user, and Discor
 
 - If there is no account associated with the identity, a new provisional account is created along with a new access token for the user.
 - If there is a provisional account associated with the identity, an access token is returned.
-- If there is an existing _full Discord account_ associated with the identity, the request is aborted (See [Error Handling](/docs/discord-social-sdk/development-guides/using-provisional-acounts#error-handling)).
+- If there is an existing _full Discord account_ associated with the identity, the request is aborted (See [Error Handling](/docs/discord-social-sdk/development-guides/using-provisional-accounts#error-handling)).
 
 Once authentication is complete, you can use the access token as you would a full Discord user's access token.
 
@@ -245,15 +248,14 @@ Common error codes and solutions for the server token exchange methods:
 If you are using OIDC, you may encounter more specific errors:
 
 | Code   | Meaning                           | Solution                                                                    |
+|--------|-----------------------------------|-----------------------------------------------------------------------------|
 | 530002 | Invalid issuer                    | Verify the issuer in your ID token matches your configuration               |
 | 530003 | Invalid audience                  | Check that the audience in your ID token matches your OIDC configuration    |
 | 530008 | OIDC configuration not found      | Verify your OIDC issuer URL is configured and accessible                    |
 | 530009 | OIDC JWKS not found               | Check that your OIDC provider's JWKS endpoint is accessible                 |
 | 530020 | Invalid OIDC JWT token            | Ensure your OIDC ID token is properly signed and formatted                  |
 
-:::info
  You can find you OIDC configuration by visiting the [Developer Portal](https://discord.com/developers/applications), selecting your application, and opening the `External Auth` page under the `Discord Social SDK` section in the sidebar.
-:::
 
 ---
 
@@ -291,11 +293,13 @@ client->UpdateProvisionalAccountDisplayName("CoolPlayer123", [](discordpp::Clien
 
 When a player wants to convert their provisional account to a full Discord account, we start a special version of the [access token request flow](/docs/discord-social-sdk/development-guides/account-linking-with-discord#requesting-access-tokens) where the provisional users external identity is included.
 
-- If you have a backend, follow [Merging Provisional Accounts for Servers](/docs/discord-social-sdk/development-guides/using-provisional-acounts#merging-provisional-accounts-for-servers)
-- If you do not have a backend, follow [Merging Provisional Accounts for Public Clients ](/docs/discord-social-sdk/development-guides/using-provisional-acounts#merging-provisional-accounts-for-public-clients)
+- If you have a backend, follow [Merging Provisional Accounts for Servers](/docs/discord-social-sdk/development-guides/using-provisional-accounts#merging-provisional-accounts-for-servers)
+- If you do not have a backend, follow [Merging Provisional Accounts for Public Clients ](/docs/discord-social-sdk/development-guides/using-provisional-accounts#merging-provisional-accounts-for-public-clients)
 
 ### Merging Provisional Accounts for Servers
 
+Merging is as simple as including `external_auth_type` and `external_auth_token` in a request to `/oauth2/token`. Discord will look up the Provisional User associated with the provided identity and attempt to merge it in to the full Discord account that generated the provided `code`.
+
 #### Desktop & Mobile
 
 ```python
@@ -304,7 +308,7 @@ import requests
 API_ENDPOINT = 'https://discord.com/api/v10'
 CLIENT_ID = '332269999912132097'
 CLIENT_SECRET = '937it3ow87i4ery69876wqire'
-EXTERNAL_AUTH_TYPE = 'OIDC'
+EXTERNAL_AUTH_TYPE = 'OIDC' # See External Auth Types above
 
 def exchange_code_with_merge(code, redirect_uri, external_auth_token):
   data = {
@@ -425,6 +429,19 @@ When a user merges their provisional account with a Discord account, the followi
 
 This migration ensures users don't lose their social connections built while using the provisional account.
 
+
+### Merge Request Failures
+
+You may receive a merge specific error code while attempting this operation:
+
+| Code   | HTTP Status | Meaning                                    | Solution                                                                   |
+|--------|-------------|--------------------------------------------|--------------------------------------------------------------------------- |
+| 530014 | 400         | Invalid merge source                       | The source account is not provisional                                      |
+| 530016 | 400         | Invalid merge destination                  | The destination account is provisional                                     |
+| 530017 | 400         | Merge source user banned                   | The provisional account being merged is banned from platform               |
+| 530023 | 400         | Too many application identities            | User already has an associated external identity for this application      |
+| -      | 423         | Resource locked                            | Transient error, wait and retry                                            |
+
 ---
 
 ## Unmerging Provisional Accounts
@@ -552,6 +569,16 @@ When a user unmerges their account, a new provisional account is created with a
 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:
+
+Code   | HTTP Status | Meaning                                    | Solution                                                                   |
+|--------|-------------|--------------------------------------------|--------------------------------------------------------------------------|
+| 50229  | 400         | Invalid user type                          | User account is provisional and cannot be unmerged                       |
+| -      | 404         | Unknown user                               | No user identity found for the provided external identity                |
+
+
 ---
 
 ## Next Steps
