🏆Tournaments API

Game implementation of the tournaments tool.

After completing the required steps; For the implementation on the game side, we tried to make it in the simple but most secure way. Please, make sure to use the Development API key during the development and testing of your integration to work with a private tournament and avoid having test data in production. This key will only work for private tournaments.

We have defined two core endpoints: get tournaments and submit scores.

Client Side: Get Tournaments

The first part of the implementation takes place on the game client/backend side. This first endpoint will provide the active tournaments for your game, given an API Key.

The most critical element will be the _id field, as it will define which tournament you want to submit the player's score to in the second part of the implementation.

Please notice that you'll only be able to access private tournaments and submit scores using a Development API Key.

We recommend adding the active tournament with a visible component in the game so that the player can select and play to it (or instead set it as default).

Get Tournaments

GET https://kend.elixir.app/sdk/v2/tournaments/

Retrieves all the tournaments for a given API Key.

Query Parameters

Name	Type	Description
filter	ALL or ACTIVE	Filter between ALL events or ACTIVE events. Default: "ACTIVE"

Headers

Name	Type	Description
x-api-key*	String	Public Key available on the Developer Dashboard

200: OK

{
"code": 1, 
"success": true, 
"data": [{
    "_id": // Unique identifier of the event (ID),
    "name": // Name of the event (STRING),
    "gameId": // ID,
    "description": // text,
    "createdAt": // Date of creation of the tournament (2022-12-13T12:45:17.281Z) "modifiedAt": Date of latest modification(ISO),
    "startsAt": // Starting date of the event(ISO),
    "endsAt": // Ending Date of the event(ISO),
    "repeatEvery": null,
    "location": // URL where the tournament is happening (String), 
    "eventUrl": // URL to redirect to the event (String),
    "userId": // Creator of the event (ID),
    "imageUrl": // URL with the image of the event (String),
    "prizePool": // Amount of USD in the prize pool (Number),
    "type": // Indicator if it is a "tournament" or just an "event",
    "visibility": // Indicator if the tournament is visible for the public (public/private), "rules": URL to the rules of the tournament (String),
    "prizeDescription": // Short description of the price (String),
    "settingsId": // Setting selected for the tournament (ID),
    "leaderboard": // Object containing the current leaderboard
} ]
}

Server Side: Submit Score

This second part of the implementation is the most critical one. Here you'll submit each player score, which will affect its ranking and be displayed in the leaderboard.

Given the critical nature of this functionality, we need to insist on the importance of calling this method from the Game Server or Backend.

You won't be able to submit a score to a public event with a Development API Key

We have chosen to be extra cautious and secure it with an RSA Signature using your private API key. We use this signature method to be sure that the score is sent from a verified server and reduces vulnerabilities and exploits of malicious agents. This provides reliability to the leaderboards displayed in Elixir.

To implement this accurately, the game developer must never expose his private key. And this should be done server-side, not client-side!

You can submit multiple scores for each player. The scores will be grouped by the defined userId or externalUserId you provide with each score, and the total aggregate result will be displayed in the leaderboard.

Submit Score

POST https://kend.elixir.app/sdk/v2/tournaments/:tournamentId/submit

Saves a user scores for a specific tournament. Either userId or externalUserId must be provided. userId represents the Elixir user Id, and will be linked to the Elixir account of the player to display their preferred username and avatar in the leaderboard, so we encourage you to use the User Info endpoint to retrieve the elixir Id of each player for the best looking tournament page. The format of the scores must follow the scoreTypes defined on your tournament settings: { "scoreType": <scoreType>, "value": Number}

Headers

Name	Type	Description
x-api-key*	String	Public Key obtained in the developer dashboard
x-api-token*	String	Timestamp used in the API Signature
x-api-signature*	String	Generated RSA signature
Content-Type	String	'application/json'

Request Body

Name	Type	Description
userId	String	Elixir User Id.
externalUserId	String	Your unique identifier for that user. (displayed if not linked to Elixir)
scores*	Array	An Array of individual scores, with each element being an object of the shape { "scoreType": "<name>", "value": <number>}

200: OK

{
  "code": 1, 
  "success": true, 
  "data": {
     "_id": "7e410239-5113-4e8c-bad2-fd018fb5cc64", 
     "tournamentId": "ad092f92-ce73-49df-a59f-1b423ad57463", 
     "externalUserId": "sniper-4431",
     "userId": "123",
     "scores": {
         "kills": 6, 
         "deaths": 2, 
         "kd": 3
    },
  "createdAt": "2022-12-15T00:48:32.084Z" 
  }
}

Additional Tournament Info

If you want to extract the best out of the Elixir Tournaments feature, including these two endpoints will make you stand out:

Tournament Leaderboard

You can access the tournament leaderboard via API to display it inside your game. Apart from the general ranking, you will have access to the player rank. In case you want to display it on your client or if you want to know the winners and assign rewards for a finished tournament.

Get Leaderboard

GET https://kend.elixir.app/sdk/v2/tournaments/:tournamentId/leaderboard

Obtain the total ranking for the tournament based on the sorting method you configured in the Dashboard. If you provide the player JWT, their rank will be included outside of the paginated entries.

Path Parameters

Name	Type	Description
tournamentId*	String	ID of the tournament

Headers

Name	Type	Description
x-api-key*	String	Public Key obtained in the developer dashboard
authorization	String	Bearer JWT

Request Body

Name	Type	Description
startDate	Date	Starting date that you want to consider for the leaderboard.
endDate	Date	Ending date that you want to consider for the leaderboard. (f.e. "2022-12-31")
limit	Int	The number of entries you want to display. Intended for pagination (Default: 10)
skip	Int	The number of entries you want to skip. Intended for pagination (Default: 0)

200: OK

{
    "code": 1,
    "success": true,
    "data": {
            "entries": [{
                "_id": "rega",
                "rank": 1,
                "avatarUrl": null,
                "scores": [
                    {
                        "scoreType": "kills",
                        "value": 5
                    }
                ]
            },
            {
                "_id": "09142dc7-283d-400a-b073-9a20955cb92d",
                "rank": 2,
                "avatarUrl": null,
                "name": "Groundbreaker",
                "username": "groundbreaker-1433",
                "scores": [
                    {
                        "scoreType": "kills",
                        "value": 10
                    }
                ]
            }
        ],
        "totalEntries": 2,
        "tournamentId": "ee39d5e1-b578-4409-8383-ceef384e7e8d",
        "userRank": {
            "_id": "09142dc7-283d-400a-b073-9a20955cb92d",
            "rank": 2,
            "avatarUrl": null,
            "name": "Groundbreaker",
            "username": "groundbreaker-1433",
            "scores": [
                {
                    "scoreType": "kills",
                    "value": 10
                }
            ]
    }
}

Tournament Scores

As a verifiable source, this endpoint will provide all scores given a tournament and a specific period. This way, game developers can contrast their data against the data in Elixir to avoid malicious activity and fake scores.

Get Scores

GET https://kend.elixir.app/sdk/v2/tournaments/:tournamentId/scores

Return the total tournament scores by user

Headers

Name	Type	Description
x-api-key*	String	Public Key obtained in the developer dashboard

Request Body

Name	Type	Description
startDate	Date	Starting date that you want to consider for the calculation of the scores
endDate	Date	Ending date that you want to consider for the calculation of the scores. (f.e. "2022-12-31")

200: OK

{
    "code": 1,
    "success": true,
    "data": [
        {
            "_id": "ff60d00d-9c35-4c76-93e4-4848473d8268",
            "tournamentId": "ee39d5e1-b578-4409-8383-ceef384e7e8d",
            "externalUserId": "sniper",
            "userId": null,
            "scores": {
                "kills": 5
            },
            "createdAt": "2023-01-11T14:52:31.394Z"
        },
        {
            "_id": "6ab6833d-6f96-47f9-8fd6-86212b3bfe4a",
            "tournamentId": "ee39d5e1-b578-4409-8383-ceef384e7e8d",
            "externalUserId": "Groundbreaker",
            "userId": "09142dc7-283d-400a-b073-9a20955cb92d",
            "scores": {
                "kills": 10
            },
            "createdAt": "2023-01-11T14:54:02.832Z"
        }
    ]
}