Managing Provisional Accounts

Once you've created a provisional account with one of the authentication methods — the Bot Token Endpoint, External Credentials Exchange, or Public Client Integration — this guide covers how to manage the account's access token and set its display name.

Each authentication method returns a Discord access token that expires after 7 days. You use it with the SDK just like a full Discord user's access token.

While we'd recommend generating a new access token whenever a user starts a session, you can also be notified when the access token is about to expire.

Use Client::SetTokenExpirationCallback to receive a callback when the current token is about to expire or has expired, so you can refresh it without interrupting the user's experience.

When the token expires, re-call the same method you used originally to obtain a new access token, then pass it to Client::UpdateToken.

// Register a callback to handle token expiration
client->SetTokenExpirationCallback([client](discordpp::AuthorizationTokenType tokenType) {
    // Re-acquire a new token using the same method you used originally.
    // For example, if you used GetProvisionalToken:
    std::string externalToken = GetExternalAuthToken(); // get a fresh token from your identity provider
    client->GetProvisionalToken(DISCORD_APPLICATION_ID,
        discordpp::AuthenticationExternalAuthType::OIDC,
        externalToken,
        [client](discordpp::ClientResult result, std::string accessToken, std::string refreshToken,
                 discordpp::AuthorizationTokenType tokenType, int32_t expiresIn, std::string scope) {
            if (result.Successful()) {
                // Pass the new access token to UpdateToken — no reconnect needed
                client->UpdateToken(discordpp::AuthorizationTokenType::Bearer, accessToken, [](discordpp::ClientResult result) {
                    if (result.Successful()) {
                        std::cout << "✅ Token refreshed successfully\n";
                    }
                });
            } else {
                std::cerr << "❌ Failed to refresh provisional token: " << result.Error() << std::endl;
            }
        });
});

It is suggested that these provisional tokens are not stored and instead invoke this function each time the game is launched and when these tokens are about to expire. However, should you choose to store it, it is recommended that these provisional account tokens be differentiated from "full" Discord account tokens.

Using these credentials, we'll create a limited Discord account just for your game and try to set the username for you according to the following:

• For Bot issued tokens, the preferred_global_name you specified will be used.
• For OIDC, a provisional account's display name will be the value of the preferred_username claim, if specified in the ID token. This field is optional and should be between 1 and 32 characters. If not specified, the user's display name will default to the user's unique username, which Discord generates on creation.
• For Steam session tickets, the display name of the user's Steam account is used as the provisional account's display name.
• For EOS Auth Access Tokens or ID Tokens, the name of the user's Epic account is used as the provisional account's display name. EOS Connect ID Tokens do not expose any username, and thus the game will need to configure the display name with Client::UpdateProvisionalAccountDisplayName.
• For Unity Services ID Tokens, the display name of the user's Unity Player Account is used as the provisional account's display name.

If you'd like to set the display name for a provisional account, you can use the Client::UpdateProvisionalAccountDisplayName method.

client->UpdateProvisionalAccountDisplayName("CoolPlayer123", [](discordpp::ClientResult result) {
    if (result.Successful()) {
      std::cout << "✅ Display name updated\n";
    }
  }
);

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