Challengermode
Home
Dashboard
Game Integration API
Client API
Auth API
Embeds

Auth API

User authentication

User authentication is used for calling Challengermode APIs on the behalf of a user, such as retrieving personalized data or performing user actions. For example,
•
Retrieving the user's profile
Using the /me endpoint, retrieve the authenticated user's personal Challengermode profile and their ongoing activities.
•
Retrieving personal tournament data
Querying the tournament graph in the Challengermode Client API using a personal access token allows you to fetch personal information related to the tournament, such as the user's own participation in it.
•
Joining a tournament
GraphQL mutations allow you to perform actions on behalf of a user, such as joining a tournament.
OAuth

Overview

At a high level, to get started calling the API on the behalf of a user follow these steps:
1

Configure OAuth client

The first step is to create an OAuth client within the credentials tab in your Application Dashboard.
•
Redirect URIs
You must explicitly specify the allowed redirect URIs you intend to use.
•
Client secret
For most use cases, we recommend setting up a confidential client by configuring a client secret for your application.
•
Testing
The application dashboard allows you to test retrieving a personal access token for your own account.
•
Consent screen customization
For interactive OAuth flows, the user is presented with a consent screen on Challengermode where they authorize access to their Challengermode account. This consent screen can be customized in the dashboard, useful for designing a more coherent visual experience for the end user.
2

Implement a suitable OAuth flow

We support a variety of OAuth 2.0 flows that are listed and described further down.
If you need help deciding on the most suitable flow for your application or wish to learn about the non-interactive flows we support that are not yet described in the documentation, please contact us in our developer Discord.
3

Call the APIs

Call authorized endpoints by passing the access token using Bearer authentication, providing the token in the authorization Bearer header of the request.

Concepts

Personal Access Tokens

User personal access tokens, referred to in the documentation as
Personal Access Token (PAT)
or
PAT
for short, are the tokens used for user authentication. They are short-lived access tokens and they are retrieved through Challengermode OAuth 2.0 server using standardized OAuth 2.0 flows. This authentication method is used extensively in the Challengermode Client API.Read more about User Authentication.

Account creation

For white-label integrations Challengermodesupports creating users in the background, instead of having users go through a typical OAuth consent screen step. This allows you to build a user experience where the user is never aware of Challengermode powering competitions behind the scenes.What enables a white-label solution is the
Assertion Flow
 which, by virtue of being a non-interactive OAuth flow, let's you retrieve a
PAT
and perform User Authentication without the user knowing about it.
Note that this feature is only available in some pricing tiers, so if you wish to use this feature, please contact us atdevelopers@challengermode.com

Useful resources

As Challengermode's OAuth follows the standard OAuth RFC, you can also refer to these official resources to learn more about individual endpoints or the various OAuth flows.
•
The OAuth 2.0 Authorization Framework
Challengermode's OAuth is designed based on the framework outlined in the official RFC. You can read and learn more about how it works in RFC6749.
•
Connect2id
You can find some of the endpoints Challengermodeoffers also described in Connect2id's documentation for OpenID Connect endpoints.

OAuth Flows

Authorization Code Flow

The Authorization Code Flow is the most commonly used flow. It involves redirecting the user to the authorization server, capturing their consent, and then providing the client with an authorization code. This code can then be exchanged for an access token.The authorization code is recommended for most use cases. Note that Challengermode requires the use of PKCE verification.
authorization code flow
1

Generate PKCE proof keys

The PKCE proof keys are generated on the game server as a user initiates the Challengermode OAuth login flow.
1.
Generate a URL safe code_verifier
var code_verifier = EncodeBase64(RandomBytes(32))
        .TrimEnd('=')
        .Replace('+', '-')
        .Replace('/', '_');
daV558BbhbH5GGsK0X8ukxXbBtI-NzpuvBhkmKxMXPw
2.
Save the code_verifier
Save the generated verifier related to the user and their login attempt. This will be used for the token exchange later.
Do not spread the original verifier outside of the game servers.
3.
Generate the code_challenge
Finally, a generated code challenge will be part of the ~/authorize request.
var code_challenge = EncodeBase64(sha256.ComputeHash(UTF8.GetBytes(code_verifier)))
        .TrimEnd('=')
        .Replace('+', '-')
        .Replace('/', '_');
BkUvwmR7GX1I0ag0RQXC2nosjt6EwIkmG8YF4-jhxU8
2

Direct the user to the OAuth screen

To initiate the OAuth login and consent flow, construct an authorize URL as described below and let the user open it in a browser.
https://www.challengermode.com/oauth/authorize?client_id=<application-id>&redirect_uri=<redirect_uri>&response_type=code&code_challenge=<code_challenge>&code_challenge_method=S256
The user will be presented with a login and consent flow after which they are redirected to your specificed redirect URI.
3

Handle the redirect URI OAuth callback

After the user has been authenticated, they are redirected to the redirect URI provided in the authorize request. This is typically formatted as a deep link to the game client.The authorization code will be provided as a query parameter:
gameprotocol://cm_oauth_callback?code=<...>
1.
Parse the authorization code
In the game client, parse the deep link authorization code query parameter.
2.
Pass the code to the server
Let the user log into your game server and pass the parsed authorization code to finish the OAuth flow.
4

Call the token endpoint

On the game server, look up the PKCE code verifier you generated for the user in the beginning of the OAuth flow and then call the token endpoint to exchange the authorization code for an auth token.
curl --location --request POST 'https://www.challengermode.com/oauth/token'
        --header 'Content-Type: application/x-www-form-urlencoded'
        --data-urlencode 'grant_type=authorization_code'
        --data-urlencode 'code_verifier=<code_verifier>'
        --data-urlencode 'code=<parsed_auth_code>'
        --data-urlencode 'client_id=<application-id>'
        --data-urlencode 'redirect_uri=<redirect-uri>'

Device Code Flow

This flow is optimized for devices with inconvenient input methods, for example consoles. The user is presented with a device code and a URL. By visiting this URL on another device (for example their phone) and entering the code, they authorize the primary device.
device code flow
1

Call the device endpoint

Initialize the flow on the game server by calling the
post
https://www.challengermode.com/oauth/device endpoint:
curl --location --request POST 'https://www.challengermode.com/oauth/device'
        --header 'Content-Type: application/x-www-form-urlencoded'
        --data-urlencode 'client_id=f7235d5b-b7b0-4c1d-f77a-08dac5e20ff2'
        --data-urlencode 'scope=offline_access'
The response will contain a device_codewhich is used to retrieve tokens, and auser_code that the user can use to verify their login on a separate device by navigating to the verification URI:
{
        "device_code": "NUOHyXgAoK1vdY_IhHzlZNCQlcrB1we0ZsMnw0ITI7Y",
        "expires_in": 599,
        "user_code": "1771-1157-4953",
        "verification_uri": "https://www.challengermode.com/device",
        "verification_uri_complete": "https://www.challengermode.com/device?user_code=1771-1157-4953"
    }
2

Direct the user to the verification URI

In the game client, direct the user to the verification URI together with the specificed user_code:
1.
verification_uri_complete
The most common way is to encode the verification_uri_complete value as a QR code and displaying it to the user.
2.
verification_uri
Alternatively, you may show the user the verification_uri and the user_code separately and let them open the URI manually.
The user will now go through the OAuth flow on a separate device, usually their phone:
3

Periodically call the token endpoint

After the ~/device endpoint is called, the server can begin calling the
post
https://www.challengermode.com/oauth/token endpoint periodically:
curl --location --request POST 'https://www.challengermode.com/oauth/token'
        --header 'Content-Type: application/x-www-form-urlencoded'
        --data-urlencode 'device_code=luYSmKoIUKDtkqm6ZQubkXz8Ii2CiqwlGIhS_ypsDEA'
        --data-urlencode 'client_id=<application-id>'
        --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code'
The endpoint will return a "authorization_pending" status until the user is done with the verification flow on their other device. Once the user has completed their login, the endpoint will return the requested tokens.

Refresh Token Exchange Flow

The Refresh Token Flow is designed to enable clients to obtain new
PAT
tokens without requiring the user to undergo authentication again. After the initial token expires, instead of repeating the entire authentication process, a
Refresh
token can be used to obtain a new
PAT
.If the offline_access scope is requested, you will also receive a
Refresh
token from the token endpoint. This can be used to keep the OAuth session alive. The default lifetime of refresh tokens is 3 months.
Refresh Token Exchange Flow
1

Request offline_access scope

In the authorize URL, include theoffline_access scope:
https://www.challengermode.com/oauth/authorize?client_id=<application-id>&redirect_uri=<redirect-uri>&response_type=code&scope=offline_access&code_challenge=<code-challenge>&code_challenge_method=S256
2

Exchange refresh token

Call the
post
https://www.challengermode.com/oauth/token endpoint to exchange the
Refresh
for a new
Refresh
PAT
pair. That way, sessions can be kept alive for longer than the default lifetime of a refresh token, usually refreshing when the user logs in.
https://www.challengermode.com/oauth/authorize?client_id=<application-id>&redirect_uri=<redirect-uri>&response_type=code&scope=offline_access&code_challenge=<code-challenge>&code_challenge_method=S256
3

Call the token endpoint

curl --location --request POST 'https://www.challengermode.com/oauth/token'
        --header 'Content-Type: application/x-www-form-urlencoded'
        --data-urlencode 'grant_type=refresh_token'
        --data-urlencode 'client_id=<client-id>'
        --data-urlencode 'refresh_token=<refresh-token>'

Assertion Flow

Partners only
Assertion flow supports account creation which is the most seamless user experience thatChallengermode supports, and is currently limited to partners only. If you wish to use this feature, please contact us atdevelopers@challengermode.com
Assertion flow is a non-interactive OAuth flow which, similar to the refresh token flow, only interacts with the
post
https://www.challengermode.com/oauth/token endpoint. It works by exchanging an
Assertion
which has been provided by a supported identity provider.
curl --location --request POST 'https://www.challengermode.com/oauth/token'
        --header 'Content-Type: application/x-www-form-urlencoded'
        --header 'Authorization: Basic <client-secret>'
        --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:assertion'
        --data-urlencode 'assertion=<assertion>'
        --data-urlencode 'scope=<scopes>''
The assertion is then verified byChallengermode and a
PAT
is returned for the user corresponding to the assertion subject, and in the case the user does not yet have a Challengermode account, a new account is created for them.

Account creation

When calling the
post
https://www.challengermode.com/oauth/token endpoint using the assertion flow,Challengermode can also create users if they do not already exist.The account creation feature will enable you to create Challengermodeusers from within your application, creating the most seamless user experience possible. Using the account creation feature, you can let the users participate in competitive content without ever having to leave your application. If the user later visitsChallengermode, they will be able to log in using the same identity provider you used to create their account.The following error responses are relevant when using the account creation feature:
•
403 UserBanned
This error is returned if the sign in was successful but the user is banned onChallengermode.
•
400 EmailClaimed
This error is returned if the provided email is already claimed by another user onChallengermode. In this case, we recommend redirecting the user to one of the interactive OAuth flows.
•
400 UserNameClaimed
If the preferred_username claim is included,Challengermodewill attempt generate unique username by adding a suffix to the preffered username in the case of a collision. If after this process a unqiue username can still not be found,Challengermodewill return this error.
•
400 EmailInvalid
This error is returned when the provided email is not a valid email address.

Assertions

If you are an identity provider and wish your identity to be supported in the assertion flow, please contact us atdevelopers@challengermode.com and refer to the description below for how to format your
Assertion
tokens.
The structure of
Assertion
tokens follows the RFC 7521 standard and should have the following contents:
•
Subject
Required
The user's account ID, used to identify the user onChallengermodebased on their associated connections.
Claim: sub
•
Issuer
Required
A unique identifier of the identity provider.
Claim: iss
•
Audience
Required
Value indicating thatChallengermodeis the party intended to process the assertion. Must have the value https://www.challengermode.com/oauth/token
Claim: aud
•
Email address
Required
The email address of the subject.
Claim: We recommendemail
If the user's real email can not be provided, the identity provider may provide a "masked" or "alias" email.
•
Expiry
Required
The time at which the assertion expires.
Claim:exp
•
Not before
optional
The time before which the assertion should not be accepted for processing. This is not part of the RFC 7521, but recommended by the JWT standard described in RFC 7519.
Claim:nbf
•
Assertion ID
Optional
A nonce or unique identifier for the assertion. This value, if provided, is used to prevent replay attacks.
Claim: if the token structure is a JWT, jti. Otherwise we recommend id
•
Given name
Optional
Claims indicating the given names of the subject.
Claim names: we suggest using given_name and family_name
•
Username
Optional
The user's preferred username or nickname, which if provided will be used to create the user'sChallengermodeusername in the case of creating a new account.
Claim: we suggestpreferred_username
In the case that the identity provider cannot provide this,Challengermodewill generate a random username for the user onChallengermode.
In the case of a username collision,Challengermodewill add a random suffix to their preferred username.
•
Country information
Optional
Information about the user's country of residence. This is something thatChallengermoderequire when/if the user wants to use more sensitive features on such as accessing their wallet. If it is not provided, the user will be able to provide this information later by logging intoChallengermode, however if this is provided by the identity provider up front it makes the user experience smoother.
Claim: we suggest usingcountry_code, according to the ISO 3166-1 alpha-2 format.