Publisher Level Account Linking

Publisher Level Account Linking enables a developer with multiple games to have a single authorization flow across all games in their portfolio. Players authenticate through a publisher application instead of authenticating separately for each game.

This is done by establishing a parent-child application hierarchy between the publisher application (parent), and game applications (children).

Once established, the publisher application can then perform player authentication, and its game application can be used to connect and utilize the Discord Social SDK.

This guide will show you how to:

• Set up publisher and game applications
• Exchange parent tokens for child tokens
• Use child tokens with the Discord Social SDK
• Understand token lifecycle and limitations

• Centralized Account Management: Manage user authorization at the publisher level

• Simplified Experience: Reduced friction when playing multiple games from the same publisher
• Richer Social Features: Access enriched friend data and activity across the publisher's game catalog

Publisher Level Account Linking is designed for publishers with centralized, cross-game social ecosystems. Not all multi-game publishers are a good fit.

Publisher Level Account Linking was designed to support publishers with cross-game social ecosystems. When a player links their Discord account to a publisher account and that publisher shares a social graph across games, the authorization feels natural and expected — players already understand that their friends in one game appear across all games in the portfolio.

Before committing to Publisher Level Account Linking, understand these architectural constraints:

• When a player links their Discord account to the publisher application, that authorization applies to all child game applications under the publisher
• Players cannot opt out of the Discord connection for individual games while remaining linked at the publisher level
• Revoking authorization disconnects the Discord account from the publisher account, affecting all games

Game friend lists exist at the publisher level — there are no per-game sandboxed friend lists. If you need separate friend lists per game, Publisher Level Account Linking is not the right solution.

The Publisher Authentication system uses two types of applications:

1. Publisher application (parent): Executes OAuth2 account linking and manages user authorization
2. Game application (child): Uses child access tokens obtained from the parent for Social SDK operations

The flow works as follows:

1. User authenticates once through the publisher application using standard OAuth2
2. Developer exchanges the parent access token for a child access token using the /partner-sdk/child-token endpoint
3. Child token is used to initialize the Discord Social SDK for the specific game
4. All Social SDK operations are now performed with the child token

We can view this as a table to see which responsibilities lie with the Publisher application and which lie with the game application:

Before you begin, make sure you have:

• A Discord application configured as the publisher (parent) with OAuth2 enabled
• One or more Discord applications configured as games (children)
• Social SDK integration enabled for all applications
• Contact with Discord to establish the parent-child relationships between applications

Set up your publisher application following the standard OAuth2 guidelines:

1. Navigate to the Developer Portal
2. Select your publisher application
3. Configure OAuth2 redirect URIs on the OAuth2 settings page
4. Enable the Social SDK integration
5. Note your Client ID and Client Secret

For each game application:

1. Create a new application in the Developer Portal
2. Enable Social SDK integration
3. Do not configure OAuth2 redirect URIs - game applications don't need them
4. Note the application's Client ID

To link child game applications to the parent publisher application, provide Discord with the following:

• Parent application ID (publisher)
• Child application IDs (games)

Discord will configure the relationships in their systems to enable token exchange.

When you establish a link, the child application has the following data deleted:

The parent application is unaffected - existing tokens remain valid since they can still be used in normal OAuth2 flows.

Ensure that child applications match the confidentiality setting of the parent application:

• If the parent is a confidential client (has a client secret), all children must be confidential clients
• If the parent is a public client, all children must be public clients

Publisher Level Account Linking supports both provisional accounts for users without Discord accounts and standard OAuth2 for users with linked Discord accounts.

sequenceDiagram
    participant User
    participant GameClient
    participant PublisherServer
    participant DiscordAPI

    Note over User, DiscordAPI: Standard OAuth Flow for Parent Application
    User->>DiscordAPI: Visit authorization URL
    DiscordAPI->>User: Present authorization prompt
    User->>DiscordAPI: Grant permission
    DiscordAPI->>User: Redirect with authorization code
    User->>GameClient: Authorization code provided
    GameClient->>PublisherServer: Forward authorization code
    PublisherServer->>DiscordAPI: POST oauth2/token (code + client_secret)
    DiscordAPI-->>PublisherServer: Parent access token & refresh token

    Note over User, DiscordAPI: Child Token Exchange
    PublisherServer->>DiscordAPI: POST partner-sdk/child-token (parent token + child app ID)

    Note over DiscordAPI: Validation Process
    DiscordAPI-->>PublisherServer: Return child access token (no refresh token)

    PublisherServer->>GameClient: Send child access token

    GameClient->>DiscordAPI: Establish SDK session with child token
    DiscordAPI-->>GameClient: Session established

sequenceDiagram
    participant User
    participant GameClient
    participant PublisherServer
    participant DiscordAPI

    Note over User, DiscordAPI: Provisional Account Authentication
    User->>GameClient: Authenticate via game system
    GameClient->>PublisherServer: Send game account credentials
    PublisherServer->>DiscordAPI: POST partner-sdk/token/bot<br/>(bot token + external_user_id)
    DiscordAPI-->>PublisherServer: Parent access token (provisional account)

    Note over User, DiscordAPI: Child Token Exchange
    PublisherServer->>DiscordAPI: POST partner-sdk/child-token<br/>(parent token + child app ID)

    Note over DiscordAPI: Validation Process
    DiscordAPI-->>PublisherServer: Return child access token (no refresh token)

    PublisherServer->>GameClient: Send child access token

    GameClient->>DiscordAPI: Establish SDK session with child token
    DiscordAPI-->>GameClient: Session established

Before you can exchange tokens, you must first obtain a parent access token through Discord OAuth2 authorization, or provisional account authorization using the publisher application ID.

When performing authorization with publisher level account linking, always use the publisher application ID for all authentication operations.

Follow the standard Account Linking with Discord or Using Provisional Accounts flow, using your publisher application id. This will provide you with a parent access token and refresh token.

Once you have a parent access token from the OAuth2 flow, exchange it for a child token using the /partner-sdk/child-token endpoint.

import requests

API_ENDPOINT = 'https://discord.com/api/v10'
PARENT_ACCESS_TOKEN = 'parent_token_here'
CHILD_APPLICATION_ID = '987654321098765432'
PARENT_CLIENT_SECRET = 'your_parent_client_secret'

def exchange_for_child_token(parent_token, child_app_id, parent_client_secret):
    response = requests.post(
        f'{API_ENDPOINT}/partner-sdk/child-token',
        headers={
            'Content-Type': 'application/json'
        },
        json={
            'parent_access_token': parent_token,
            'child_application_id': child_app_id,
            'parent_client_secret': parent_client_secret
        }
    )
    response.raise_for_status()
    return response.json()

# Exchange the token
child_token_data = exchange_for_child_token(
    PARENT_ACCESS_TOKEN,
    CHILD_APPLICATION_ID,
    PARENT_CLIENT_SECRET
)

print(f"Child access token: {child_token_data['access_token']}")
print(f"Expires in: {child_token_data['expires_in']} seconds")

{
  "access_token": "child_application_access_token",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "sdk.social_layer"
}

After completing the backend token exchange, you need to integrate the child token into your game client's Social SDK. This section covers how to configure the SDK to work with publisher authentication.

When your game needs to initiate authorization, always use the publisher application ID, not the game application ID:

// Use the PUBLISHER_APPLICATION_ID for authorization
discordpp::AuthorizationArgs args{};
args.SetClientId(PUBLISHER_APPLICATION_ID);  // Parent app ID, not child
args.SetScopes(discordpp::Client::GetDefaultPresenceScopes());

client->Authorize(args, [](discordpp::ClientResult result, std::string code, std::string redirectUri) {
    if (result.Successful()) {
        std::cout << "✅ Authorization successful!" << std::endl;
        // Exchange code for parent token, then exchange parent token for child token
    }
});

Once your backend provides the child token, use it to authenticate the Social SDK:

#include <discord-social-sdk/discord.h>

void InitializeSDKWithChildToken(const std::string& childAccessToken) {
    // Create SDK client instance
    auto client = std::make_shared<discordpp::Client>();

    // Update the client with the child token
    client->UpdateToken(
        discordpp::AuthorizationTokenType::Bearer,
        childAccessToken,
        [client](discordpp::ClientResult result) {
            if (result.Successful()) {
                std::cout << "✅ Token updated successfully!" << std::endl;

                // Connect to Discord
                client->Connect();
            } else {
                std::cerr << "❌ Failed to update token: " << result.Error() << std::endl;
            }
        }
    );
}

Once connected, all Social SDK operations execute in the context of the game (child) application.

Child game application token lifecycles are directly tied to their parent publisher application tokens. Understanding how game tokens behave when publisher tokens are refreshed or revoked is essential for implementing your integration correctly.

Game token expirations are tied to their parent publisher tokens:

• Game tokens expire at the same time as the publisher token
• Game token expires_in matches the publisher token's remaining lifetime
• No refresh tokens are provided for game tokens

When publisher application tokens are refreshed:

• Existing game tokens remain valid
• Game tokens will still expire at the original publisher token expiry time
• To get a new game token with updated expiry, re-exchange using the refreshed publisher token

When publisher application tokens are revoked:

• All associated child game tokens are immediately invalidated
• Any active SDK sessions using game tokens will be disconnected

When revoking tokens in a publisher-level account linking setup, it's important to understand which application ID to use for revocation.

While game tokens are issued through the publisher application's authority, revocation follows a different pattern:

• Game tokens are issued by the publisher application - The /partner-sdk/child-token endpoint uses the publisher application's credentials to issue game tokens
• Revocation uses the token's associated application ID:
  • Publisher token revocation → Use the parent publisher application ID
  • Game token revocation → Use the child game application ID

To revoke a publisher access token, use the publisher application ID and credentials:

import requests

API_ENDPOINT = 'https://discord.com/api/v10'
PARENT_CLIENT_ID = 'YOUR_PARENT_CLIENT_ID'
PARENT_CLIENT_SECRET = 'YOUR_PARENT_CLIENT_SECRET'

def revoke_parent_token(parent_token):
    data = {'token': parent_token}
    headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    r = requests.post(
        f'{API_ENDPOINT}/oauth2/token/revoke',
        data=data,
        headers=headers,
        auth=(PARENT_CLIENT_ID, PARENT_CLIENT_SECRET)
    )
    r.raise_for_status()

To revoke a game access token, use the game application ID and credentials:

import requests

API_ENDPOINT = 'https://discord.com/api/v10'
CHILD_CLIENT_ID = 'YOUR_CHILD_CLIENT_ID'
CHILD_CLIENT_SECRET = 'YOUR_CHILD_CLIENT_SECRET'

def revoke_child_token(child_token):
    data = {'token': child_token}
    headers = {'Content-Type': 'application/x-www-form-urlencoded'}
    r = requests.post(
        f'{API_ENDPOINT}/oauth2/token/revoke',
        data=data,
        headers=headers,
        auth=(CHILD_CLIENT_ID, CHILD_CLIENT_SECRET)
    )
    r.raise_for_status()

For more details on the token revocation API and additional options, see Revoking Access Tokens in the Account Linking guide.

If your studio operates a centralized publisher account system but doesn't have a shared social graph across games, you can still build your own centralized backend system that manages per-game Discord application IDs with the standard authentication model. This lets you reuse Social SDK integration logic across titles while keeping each game's Discord connection separate.

There is also potential for you to build a publisher account settings UI that lets players link, unlink, and manage which Discord account is connected to each game, giving players finer-grained control over their account linking experience.

The trade-off is that players will need to authorize each game individually, and it requires more development, but it also provides players more control over which games they link to their Discord accounts – which may well make more sense for your individual studio or game specific needs.

Now that you've set up publisher level account linking, explore more features of the Discord Social SDK:

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