Discord Publisher Authentication Technical Spec

discord_publisher_auth_spec.md

Discord Publisher Authentication Technical Spec

Motivation

The Discord Social SDK requires a Discord application configured for your game. Users grant this application permission to access their Discord data. The SDK then uses OAuth2 access tokens, obtained through this user authorization, to interact with Discord on the user's behalf.

Applications used for the SDK in this way map 1:1 with games. The title and art for the application is that of the game, and a lot of UX in the Discord app and SDK reflects this.

This means that publishers with many games require users to authorize potentially many times - one for each game they have integrated. This is cumbersome for both publisher and user, and we solve it with publisher authentication.

Overview

Publisher Authentication introduces a parent-child hierarchy between a publisher's applications:

• The publisher application (parent) is used for the OAuth2 account linking flows required to acquire and manage a user authorization.

• This is the account linking flow you likely already have.
• This is the application the user sees when they link their account.

• The game application (child) represents a game in your catalog and is used to interface with the Social SDK via a child access token.

• You configure one application per game integrating with the Social SDK.
• The user will never directly authorize the game application.

After configuring your publisher and game applications, users can grant authorization to your publisher application through typical OAuth2 account linking flows.

The parent access token can be exchanged for a child access token via the new partner-sdk/child-token endpoint. The child access token is then used for all Social SDK operations.

• Parent access tokens cannot be used to connect to Discord via the Social SDK, only child access tokens can
• Conversely, child applications cannot be used for OAuth2 account linking flows. Child access tokens can only be acquired through the token exchange flow.

Application Configuration

1. Configure your publisher application per our typical account linking guidelines.
2. Create each game application in the developer portal and customize to your liking.
   1. You don't need to configure OAuth2 redirects for these applications as user authorization is all done through the publisher application.
3. All applications must have the Social SDK integration enabled. This can be enabled by Discord engineers, or you can opt in via the "Getting Started" form in the developer portal (access will be automatically granted)

4. Reach out to Discord with the application ID of your parent application and the IDs of each of your game applications. We will establish the parent-child relationship.
5. You're good to go.

Publisher applications and game applications are restricted from certain actions. If you're using existing applications, flows may be broken as soon as we establish the relationship. Work with us to make sure the migration goes smoothly, or create new applications for a clean slate.

Token Exchange

Prior to connecting with the social SDK, exchange a publisher access token for a child access token via a POST request to partner-sdk/child-token

// POST partner-sdk/child-token
{
  "parent_access_token": str,        // Publisher application access token
  "child_application_id": int,       // Game application ID
  "parent_client_secret": Optional<str>, // Publisher application secret
}

// EXAMPLE RESPONSE
{
  "access_token": "<access token>",
  "token_type": "Bearer",
  "expires_in": 604800,              // Child token expiry will match parent
  "scope": "sdk.social_layer"        // Child token scopes will match parent
}

• No refresh token is returned for the child application, you are expected to perform this token exchange whenever you need a new token
• The child access token will be about as long lived as the parent access token
• Revocation of a parent token invalidates all of its children's tokens. This will happen when a user deauthorizes the publisher application
• Refreshing a parent token does not invalidate children's token. Existing child tokens will not be refreshed by this action, however, and will need to be updated by a child token exchange when they expire.
• A client secret is required when the parent application is a confidential client. Public clients do not have this restriction. A child application's public / confidential setting must match that of the parent.

Social SDK Usage

When using the Social SDK or related API endpoints to perform authorization - use the publisher application ID. This means calls to:

• Client::Authorize
• Client::GetToken and oauth2/token
• Client::GetProvisionalToken and partner-sdk/token

All should be used with the publisher application ID. Calls with the game application ID will fail.

Once you have a game token, pass it into Client::UpdateToken and use the SDK as usual - further SDK operations will operate under the context of the game.

Discord server APIs which accept OAuth Bearer authorization should be invoked with the child access token.

User Experience Differences

Most SDK features will work identically to if you had just created a regular Social Layer game application. The main differences center around sharing information between games in your catalog.

Normally we limit the amount of game data that is shared between SDK sessions in different games. For example, we wouldn't show that your friend is playing "Minecraft" when you're in a totally different game. Similarly, based on user settings, we may limit the messages a user receives to only messages from other people in the same game.

If the SDK is connected to a child game session, we relax this restriction for other children of your publisher application. So the SDK connected via Game Foo will be able to see rich presence for a friend in Game Baz if both Foo and Baz share a parent.

Outside of sharing data across different game sessions, the user experience should feel the same. Messages will appear as though they were sent from the game, rich presence will be attributed to the game - the publisher application exists in the background and is invisible to the user during the game session.

Changelog

• 4/25/2025:
  • Initial draft
• 5/20/2025:
  • Update client_id parameter name in route
• 6/05/2025:
  • Update params, add client secret, call out public vs confidential client types
• 6/16/2025:
  • Clarify behavior around token refresh, improve clarity around oauth API endpoints, clarify that the social integration is required
• 6/17/2025:
  • Fix type of client secret