Challengermode
Home
Dashboard
Game Integration API
Client API
Auth API
Embeds

Game Integration API

Game account linking

The Game Account Linking APIs revolves around the concept of game accounts, which represents a player's identity in your game.Through the Game Account Linking process, you'll provide a GameAccount object toChallengermode which will be used to reference the player in your game, as well as optional additional game account data. Integrating the game account linking APIs is an essential step to integrating any game to Challengermode. Linking game accounts serves two main purposes:
•
Verify the user's identity
The account linking process ensures that the user can verify their identity inside your game which confirms account ownership and increases trust when playing competitively.
•
Determining game account ID
The game account ID Challengermode obtains during the account linking process is the game account ID it will use in all subsequent communication with the game's backend, e.g. to create game sessions.
Note thath this step is a prerequisite for Game Handling as it providesChallengermode the necessary information to reference users that will be participating in competitions.
There are multiple methods to link game accounts for you to choose from depending on your game and backend capabilities. Each method is configurable in the account linking section of your Application Dashboard.

Concepts

Game Accounts

The GameAccount represents a user's player account that they are logged to play and participate in competitions.This is the account that is linked and updated through the Game Account Linking APIs.

Game Account References

The GameAccountReference is a reference to a user's GameAccount and used throughout the API refer to a player's account in the context of a competition.The accountId field is the ID which was obtained during the Game Account Linking process.For example, for the Create Game Session process, game account references are used to specify which players should be invited to a new game session.

Game Account Login

When referring to a player's game account, it is important to emphasize that this is separate from how they logged into that account.For example, if you have a multi-platform game a player might have logged into their game account both through Epic games services and on their PlayStation.If you provide an optional list of DomainHints to the GameAccount to specify which third-party identity providers the player can use to log in,Challengermode can use this to provide better defaults for the player when interacting with Challengermode services.

Components

OAuth account linking

OAuth account linking works by retrieving a
OTT
account linking token on behalf of the user by calling
post
generate_verification_token using User authentication, and then posting the linking token to the
post
verify-game-account endpoint.
OAuth account verification
1

Retrieve a personal access token

Retrieve a
PAT
 throughChallengermode OAuth using a flow suitable for your game.
2

Generate an account linking token

Using the personal access token 
PAT
, generate an account linking token 
OTT
by calling the 
post
generate-verification-token endpoint.
curl --location --request POST
    'undefined/mk1/v1/game_integrations/<game-integration-id>/link_account/generate_verification_token'
    --header 'Authorization: Bearer <personal-access-token>'
3

Use the linking token to link the game account

Send the linking token together with the user's game account ID toChallengermode's 
post
verify-game-account endpoint.
curl --location --request POST
    'https://publicapi.challangermode.com/mk1/v1/game_integrations/<game-integration-id>/link_account/verify'
    --header 'Authorization: Bearer <bot-access-key>'
    --header 'Content-Type: application/json'
    --data-raw '{
    "accountLinkingToken": <account-linking-token>,
        "gameAccountReference": {
            "accountId": <internal-account-id>
        }
    }'

SSO game account linking

The SSO account linking method verifies the player using the identifier from a configured third-party SSO provider (e.g. Steam) via the 
event
verify-game-account event.
SSO account linking
You'll find the configuration to support this account linking method in your Application Dashboard → account linking → SSO account linking.
1

Configure webhook

The first step is to configure the webhook that will be used to handle the 
event
verify-game-account event. This webhook will be called when the user wants to link their account.
2

Configure supported identity providers

Next, configure the third-party identity providers your game supports.Challengermodecurrently supports the following identity providers:
Steam
Steam
EA
EA
Battle.net
Battle.net
Ubisoft
Ubisoft
Apple
Apple
Microsoft Live
Microsoft Live
3

Handle the event

event
verify-game-account will be called when a user wants to link a game account. The payload will specify the identity provider (e.g. Steam) and contain the domain-specific account ID (e.g a Steam ID).To handle the event, the game backend should:
•
Look up the user
Look up the user corresponding to the external provider ID.
•
Return the game account ID
If the user exists, return their game account ID.

Intent game account linking

The intent account linking method verifies the player by opening the game client through the 
device
verify-game-account intent, passing an account linking token 
OTT
 to the game client. To link the account, send this linking token to your backend, and then post the token to the 
post
verify-game-account endpoint.The round trip through the game client, game backend, and Challengermode ensures that the user rightfully owns the game account being linked.
Intent account verification
You'll find the configuration to support this account linking method in your Application Dashboard → account linking → intent account linking.
1

Configure supported platforms

The first step is to configure the platforms that should support this account linking method. You can read more about platform configuration here.
2

Parse the intent on the device

When the intent is invoked on the device, parse the linking token 
OTT
contained in the intent payload.
ott = ParseIntent(intent)
3

Inform the player (optional)

We encourage you to render an dialog to confirm the user's intent to link their game account toChallengermode before proceeding.
4

Pass the linking token to your backend

Pass the account linking token 
OTT
to your backend server over an authenticated channel.
LoginToBackend()
    SendOttToBackend(ott) // send ott to backend over authenticated channel
5

Verify the game account

The server should now authenticate the user to then submit the linking token 
OTT
together with the user's game account ID toChallengermode's 
post
verify-game-account endpoint.
accountId = authorizedUser.Id
    ChallengermodeClient.VerifyAccount(gameAccountReference:{accountId: accountId}, accountLinkingToken: ott)

Game account details

When the account linking process is complete, There are two ways to provide additional game accounts information to Challengermode:
•
Implement the get-game-account webhook
Listen to the
event
get-game-account webhook and returning a GameAccount.
•
Post the game account
Upload a GameAccount directly through the
post
game-accounts endpoint.
While only the basic game account reference is necessary, providing additional information can improve the user experience. For example, displaying the user's profile picture or in-game name in theChallengermode UI.

Implement the get-game-account webhook

The
event
get-game-account webhook event will be called directly after a user links their game account and wheneverChallengermode needs to retrieve or update the information about a game account.
Game account details
1

Configure webhook

You'll find the configuration for the game account details webhook in your Application Dashboard → account linking → game account details.
2

Handle the event

Your webhook should handle the 
event
get-game-account event by parsing the game account ID provided in the payload and returning a GameAccount.
{
        "gameAccountReference": { "accountId": "<game-account-id>" },
        "displayName": "SpinToWin",
        "profileImageUrl": "https://gamecdn/path-to-profile-img",
    }
Most properties of the game account model are optional but improve the overall user experience.

Post game accounts

Whenever your game account is updated, post the updated GameAccount to Challengermode using the 
post
game-accounts endpoint.
curl --location --request POST
        'https://publicapi.challangermode.com/mk1/v1/game_integrations/<game-integration-id>/game_accounts/{gameAccountId}'
        --header 'Authorization: Bearer <bot-access-key>'
        --header 'Content-Type: application/json'
        --data-raw '{
            "gameAccountReference": { "accountId": <game-account-id> },
            "displayName": "SpinToWin",
            "profileImageUrl": "https://gamecdn/path-to-profile-img",
        }'