This guide is intended to help you as a game developer navigate the Challonge Connect API by addressing common use cases and highlighting the most relevant API endpoints.

Getting Started

No matter your platform or engine, the first thing you’ll need to do is register a new Challonge developer application at https://connect.challonge.com. Everything can be edited later, so don’t worry if you don’t have an application or redirect (for OAuth callback) URL yet.

Download Helpful Resources

Next, it’s helpful to know what resources are available for your game development platform. While these can add conveniences and speed up development, Challonge Connect will work in any environment where JSON API requests can be made.

1. Unity
   1. See demo and asset in Open Source Libraries
2. Godot
   1. Open source libraries and scenes available upon request (pending future open source release)
3. Unreal Engine
   1. Development planning is still underway

Review In-Game Integration Use Cases

1. Authenticate a Challonge user in-game:

   Authentication: Use our Device Grant OAuth flow. Postman doc: https://documenter.getpostman.com/view/11915787/U16jN6TK#3d1082d9-c237-4cef-aae3-49c877681228

   Scopes: — me: you definitely want this one. It allows your app to view the user’s details. — application:organizer: allows your app to create and manage tournaments on the user’s behalf that are connected to your app. This includes read and write access to the participants, matches, and other resources associated with these tournaments. — application:player: if application:organizer is more than you need, you can instead opt to request this player scope. It allows you to view tournaments connected to your app that the user is registered for, allows you to register the user for tournaments, and allows you to report scores on behalf of the user (note: Challonge policies limit which matches they can edit. An organizer can edit all matches for their tournament, but a player typically can only edit matches they’re participating in).

   • Get a device code (part of the device authorization grant flow)
     • Allows the user to sign in using their PC or phone
     • POST https://connect.challonge.com/oauth/authorize_device
   • Poll for an access token using the device code (part of the device authorization grant flow)
     • Once the user signs in and grants your game access, you’ll be given an access token
     • POST https://connect.challonge.com/oauth/token
   • Get an access token using a refresh token
     • Once an access token expires, you can fetch a new one without requiring the user to sign in again.
     • POST https://api.challonge.com/oauth/token, with grant_type: “refresh_token”

2. Access read-only information for your game as the signed-in user:

   Authentication: access token from device authorization grant OAuth flow

   • Get the signed-in user’s details (requires “me” scope)
     • GET https://api.challonge.com/v2/me.json
   • Get list of all tournaments
     • GET https://api.challonge.com/v2/application/tournaments.json
   • Get list of tournaments the user organized
     • GET https://api.challonge.com/v2/application/tournaments.json?organizer_id={user-id}
       • can be https://api.challonge.com/v2/application/organizers/${username}/tournaments.json
   • Get list of tournaments the user is registered for
     • GET https://api.challonge.com.v2/application/tournaments.json?participant_user_id={user_id}
   • Get details of a tournament
     • GET https://api.challonge.com/v2/application/tournaments/{tournament-id}.json

3. Perform player actions as the signed-in user:

   Authentication: access token from device authorization grant OAuth flow

   • Register the user for any tournament associated with your game, without requiring an invitation (requires “application:player” scope)
     • POST https://api.challonge.com/v2/application/tournaments/{tournament-id}/participants/register_me.json

4. Manage tournaments for the signed-in user (client-side): NOTE: These requests are only intended for games that are local or peer-to-peer. Due to there being no server for validating game state and preventing cheating, local client match results have to be trusted. Implementing request signing is strongly recommended to prevent easier forms of cheating (see https://www.notion.so/Security-3440fc9411bd40d0af1509e629e4bb64)

   Security

   Authentication: access token from device authorization grant OAuth flow

   • Create a tournament organized by the signed-in user (requires “application:organizer” scope)
     • POST https://api.challonge.com/v2/application/tournaments.json
   • Edit tournament state (requires “application:organizer” scope, and signed in user must be an admin of the tournament)
     • PUT https://api.challonge.com/v2/application/tournaments/{tournament-id}/change_state.json
   • Register plain text participant entries (requires “application:organizer” scope, and signed in user must be an admin of the tournament)
     • Enter text names into a bracket that aren’t associated with Challonge users
     • POST https://api.challonge.com/v2/application/tournaments/{tournament-id}/participants.json
   • Report match scores (requires “application:organizer” scope or “application:player” scope)
     • For 3+ player formats (FFA, leaderboard, race, grand prix), the user can only report their own score, unless they’re the tournament organizer.
     • For 2 player formats (single elimination, double elimination, round robin, Swiss), the user can only report scores for open matches they’re participating in, unless they’re the tournament organizer
     • PUT https://api.challonge.com/v2/application/tournaments/{tournament-id}/matches/{match-id}.json

5. Manage any tournament associated with your game (server-side): NOTE: Requires client-server architecture where you can secure private keys on servers. This architecture is recommended if your players have any incentive to cheat (global high score leaderboards, player ratings, rewards for winning tournaments).

   Authentication: access token from client credentials OAuth flow

   Scopes: — application:manage: full access to all tournaments connected to your app. This scope can only be obtained via the client credentials flow and should be carefully protected.

   • Create a tournament organized by the owner of the Challonge developer app or its official community
     • POST https://api.challonge.com/v2/application/tournaments.json
   • Edit tournament state
     • PUT https://api.challonge.com/v2/application/tournaments/{tournament-id}/change_state.json
   • Register participants
     • POST https://api.challonge.com/v2/application/tournaments/{tournament-id}/participants.json
   • Report verified match scores
     • POST https://api.challonge.com/v2/application/tournaments/{tournament-id}/participants.json

Understand WebPlay

One of the greatest parts about integrating Challonge Connect into your game is that you extend the reach of your game to Challonge.com. This means:

• People can create tournaments on Challonge.com that are visible in your game, and vise-versa.