Bot Token Endpoint

Use the Bot Token Endpoint if your game has an account system which uniquely identifies users.

You pass your account system's unique ID for the user, and Discord returns an access token — creating a provisional account for that identity if one does not already exist.

No identity provider configuration is required for this method.

If you have a hard requirement for a turnkey OIDC integration, see External Credentials Exchange; if you don't have a backend, see Public Client Integration.

Your backend exchanges the player's identity for a Discord access token. Keep this call and your bot token on the server, exposed to the client through your own authenticated endpoint:

# filepath: your_game/server/auth.py
import requests
from models import GameAccount

def get_provisional_token(game_account: GameAccount):
  response = requests.post(
    'https://discord.com/api/v10/partner-sdk/token/bot',
    headers={
      'Content-Type': 'application/json',
      'Authorization': 'Bot <BOT_TOKEN>' # your application's bot token
    },
    json={
      'external_user_id': game_account.id,       # your account system's unique id
      'preferred_global_name': game_account.display_name, # your account system's display name for the user
    }
  )
  return response.json()

{
  "access_token": "<access token>",
  "id_token": "<id token>",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "sdk.social_layer"
}

The game client receives the access_token from your backend — it never sees the bot token — and passes it straight to the SDK. Set your application ID, call Client::UpdateToken with the token as a Bearer token, then Client::Connect:

// filepath: your_game/client/connect.cpp
// `accessToken` was returned by YOUR backend, not requested directly from Discord.
client->SetApplicationId(DISCORD_APPLICATION_ID);

client->UpdateToken(discordpp::AuthorizationTokenType::Bearer, accessToken,
    [client](discordpp::ClientResult result) {
      if (result.Successful()) {
        client->Connect();
      } else {
        std::cerr << "Failed to update token: " << result.Error() << '\n';
      }
    });

Because your bot token never reaches the client, the client can't call Discord's bot token endpoint directly. Instead, your server brokers the request:

1. The player signs in with your own account system, as they normally would.
2. The game client asks your backend for a Discord provisional token.
3. Your backend calls Discord's /partner-sdk/token/bot endpoint — authenticated with your bot token — passing the player's external_user_id (and optional preferred_global_name), and returns the resulting access_token to the client.
4. The client hands that token to the SDK with Client::UpdateToken and calls Client::Connect.

sequenceDiagram
    autonumber
    actor P as Player
    participant C as Game Client (SDK)
    participant B as Your Game Backend
    participant D as Discord API

    P->>C: Sign in with your account system
    C->>B: Request a Discord provisional token<br/>(authenticated with your own session)
    Note over B: Your bot token lives only here
    B->>D: POST /partner-sdk/token/bot<br/>Authorization: Bot <token><br/>{ external_user_id, preferred_global_name }
    alt No account for external_user_id
        D->>D: Create provisional account
        D-->>B: 200 { access_token, id_token, ... }
    else Provisional account exists
        D-->>B: 200 { access_token, id_token, ... }
    else Full Discord account exists
        D-->>B: Error 530010 (use OAuth2 flow)
    end
    B-->>C: access_token
    C->>D: Client::UpdateToken(Bearer, access_token)
    C->>D: Client::Connect()
    D-->>C: Connected (status: Ready) — ready to use Social SDK features

Once authentication is complete, you can use the access token as you would a full Discord user's access token. See Managing Provisional Accounts for token refresh, storage, and display names.

Common error codes and solutions when creating a provisional 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