Bot Token Endpoint

Server Authentication with Bot Token Endpoint

This is the preferred method of authentication. It ends up being the simplest and most flexible choice for most provisional account integrations.

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 bot token is a privileged secret — it must stay on your backend and never ship in the game client. The client receives only the provisional access_token your backend returns. See How the Integration Fits Together for the full flow.

Server: Create the Provisional Token

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()

Bot Token Endpoint Response

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

Client: Connect With the Token

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';
      }
    });

How the Integration Fits Together

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:

The player signs in with your own account system, as they normally would.
The game client asks your backend for a Discord provisional token.
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.
The client hands that token to the SDK with Client::UpdateToken and calls Client::Connect.

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.

Error Handling

Common error codes and solutions when creating a provisional account:

Code	Meaning	Solution
530000	Application not configured	Contact Discord support to enable provisional accounts for your application
530001	Expired ID token	Request a new token from your identity provider
530004	Token too old	Request a new token (tokens over 1 week old are rejected)
530006	Username generation failed	Retry the operation (temporary error)
530007	Invalid client secret	Verify or regenerate your client secret in the Developer Portal
530010	User account non-provisional	User already linked to Discord account - use standard OAuth2 flow

Next Steps

Managing Provisional Accounts

Refresh access tokens and set display names.

Merging Accounts

Merge a provisional account into a full Discord account.

Unmerging Accounts

Sever the link between a Discord account and 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

Change Log

Date	Changes
July 14, 2026	Split into its own page with the client-to-server integration flow
March 17, 2025	Initial release

Discord Social SDK

Core Concepts

Getting Started

Design Foundations

Provisional Accounts

Discord Account Linking

Friends & Relationships

Rich Presence & User Status

Game Invites

Direct Messages

Lobbies & Voice

How To

Server Authentication with Bot Token Endpoint

Server: Create the Provisional Token

Bot Token Endpoint Response

Client: Connect With the Token

How the Integration Fits Together

Error Handling

Next Steps

Managing Provisional Accounts

Merging Accounts

Unmerging Accounts

Change Log

​Server Authentication with Bot Token Endpoint

​Server: Create the Provisional Token

​Bot Token Endpoint Response

​Client: Connect With the Token

​How the Integration Fits Together

​Error Handling

​Next Steps

Managing Provisional Accounts

Merging Accounts

Unmerging Accounts

​Change Log

Server Authentication with Bot Token Endpoint

Server: Create the Provisional Token

Bot Token Endpoint Response

Client: Connect With the Token

How the Integration Fits Together

Error Handling

Next Steps

Change Log