Challonge API Docs
  1. Challonge Connect
Challonge API Docs
  • Guides
    • Welcome
    • Changelog
    • Upgrading
      • Upgrading from v2.0 to v2.1
    • Sample Use Cases
      • Running a Two-Stage Tournament
    • Challonge Connect
      • About
      • Game Integration (beta)
      • Connect Request Signing
  • API v2.1
    • Getting Started
    • Authorization
    • Error Responses
    • Resource Scoping
    • OAuth
      • Scopes
      • Grant Request
      • Token Request
      • Refresh Token Request
      • Device Grant Authorization Request
      • Device Grant Access Token Request
    • Tournament API
      • Tournaments
        • Tournament States
        • List Tournaments
        • Create Tournament
        • Get Tournament
        • Update Tournament
        • Delete Tournament
        • Change Tournament State
      • Participants
        • List Participants
        • Create Participant
        • Get Participant
        • Update Participant
        • Delete Participant
        • Bulk Create Participants
        • Clear All Participants
        • Randomize Participants
        • Register Me
      • Matches
        • List Matches
        • Get Match
        • Update Match
        • Change Match State
      • Match Attachments
        • List Match Attachments
        • Create Match Attachment
        • Delete Match Attachment
    • Race API
      • Races
        • List Races
        • Create Race
        • Get Race
        • Update Race
        • Delete Race
        • Change Race State
      • Rounds
        • List Rounds
        • Get Round
        • Update Round
      • Elapsed Times
        • List Elapsed Times
        • Get Elapsed Time
        • Update Elapsed Time
        • Bulk Update Elapsed Times
    • Get User
      GET
    • List Communities
      GET
    • Schemas
      • MatchAttachmentModel
      • MatchAttachmentInput
      • MatchAttachmentOutput
      • MatchAttachment
      • ParticipantModel
      • ParticipantOutput
      • ParticipantInput
      • ParticipantBulkInput
      • Participant
      • TournamentModel
      • TournamentInput
      • Tournament
      • TournamentStateInput
      • CommunityModel
      • Community
      • MatchModel
      • MatchInput
      • MatchOutput
      • Match
      • MatchStateInput
      • ErrorModel
      • UserModel
      • User
      • ElapsedTimeBulkInput
      • ElapsedTimeWithID
      • ElapsedTimeOutput
      • ElaspedTimeInput
      • Timestamps
      • RelationshipLink
      • RoundOutput
      • RoundStateInput
      • RacingOutput
      • RacingInput
      • RacingStateInput
  • Bracket JSAPI v1.0
    • Getting Started
    • Broadcasted Events
    • API Actions
      • scrollToCoordinates
      • scrollToMatchIdentifier
      • setZoomScale
      • zoomToCoordinate
      • zoomToMatchIdentifier
      • loadTheme
      • filterRounds
      • loadIntegrationData
      • setBracketSettings
  • API v2.0 (deprecated)
    • About
    • Deprecated Endpoints
      • Tournament
        • findTournaments
        • createTournament
        • showTournament
        • updateTournament
        • deleteTournament
        • changeStateTournament
      • Match
        • findMatches
        • showMatch
        • updateMatch
        • changeStateTournament
      • Participant
        • findParticipants
        • createParticipant
        • showParticipant
        • updateParticipant
        • deleteParticipant
        • bulkCreateParticipant
        • clearAllParticipants
        • randomizeParticipants
      • Match Attachment
        • findMatchAttachments
        • createMatchAttachments
        • deleteMatchAttachment
      • Race
        • findRaces
        • createRace
        • showRace
        • updateRace
        • deleteRace
        • changeStateRace
      • Round
        • findRounds
        • showRound
        • updateRound
      • Elapsed Time
        • findElapsedTime
        • showElapsedTime
        • updateElapsedTime
        • bulkUpdateElapsedTime
      • User
        • findUser
        • findCommunities
    • Schemas
      • MatchAttachmentModel
      • MatchAttachmentInput
      • MatchAttachmentOutput
      • MatchAttachment
      • ParticipantModel
      • ParticipantOutput
      • ParticipantInput
      • ParticipantBulkInput
      • Participant
      • TournamentModel
      • TournamentInput
      • Tournament
      • TournamentStateInput
      • CommunityModel
      • Community
      • MatchModel
      • MatchInput
      • MatchOutput
      • Match
      • MatchStateInput
      • ErrorModel
      • UserModel
      • User
      • ElapsedTimeBulkInput
      • ElapsedTimeWithID
      • ElapsedTimeOutput
      • ElaspedTimeInput
      • Timestamps
      • RelationshipLink
      • RoundOutput
      • RoundStateInput
      • RacingOutput
      • RacingInput
      • RacingStateInput
  • API v1 (deprecated)
    • About
    • Deprecated Endpoints
      • Tournaments
        • List tournaments
        • Create a tournament
        • Get a tournament
        • Update a tournament
        • Delete a tournament
        • Process check-in results for a tournament
        • Abort check-in for a tournament
        • Start a tournament
        • Finalize a tournament
        • Reset a tournament
        • Open for predictions
      • Participants
        • List a tournament's participants
        • Create a participant
        • Bulk create participants
        • Get a participant
        • Update a participant
        • Check in a participant
        • Undo check-in for a participant
        • Delete/deactivate a participant
        • Clear/delete all participants
        • Randomize a tournament's participants
      • Matches
        • List a tournament's matches
        • Get a match
        • Update a match
        • Reopen a match
        • Mark a match as underway
        • Unmark a match as underway
      • Match Attachments
        • List a match's attachments
        • Create a match attachment
        • Get a match attachment
        • Update a match attachment
        • Delete a match attachment
  1. Challonge Connect

Game Integration (beta)

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.
image.png

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
Challonge Connect Unity game demo (includes our Unity asset)
v0.1.0 download: https://drive.google.com/file/d/1EaCKL7UoDJA6oZ4dxxf9HKTNBbSUer54/view?usp=sharing
To run, open with Unity, and plug your application’s client id into Assets/Challonge/Settings/My Challonge Application.asset
2.
Godot
Open source libraries and scenes available upon request (pending future open source release)

Review In-Game Integration Use Cases#

1.
Authenticate a Challonge user in-game:
Authentication: Use the Device Authorization Grant Flow (see Authorization)
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 /oauth/authorize_device (Device Grant Authorization Request)
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 /oauth/token (Device Grant Access Token Request)
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 /oauth/token (Device Grant Access Token Request), 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 /v2.1/me (Get User)
Get list of all tournaments
GET /v2.1/application/tournaments (List Tournaments)
Get list of tournaments the user organized
GET /v2.1/application/tournaments?organizer_id={user_id} (List Tournaments)
can be /v2/application/organizers/${username}/tournaments.json
Get list of tournaments the user is registered for
GET /v2.1/application/tournaments?participant_user_id={user_id} (List Tournaments)
Get details of a tournament
GET /v2.1/application/tournaments/{tournament_id} (Get Tournament)
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 /v2.1/application/tournaments/{tournament_id}/participants/register_me (Register Me)
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 Connect Request Signing)
Authentication: access token from device authorization grant OAuth flow
Create a tournament organized by the signed-in user (requires application:organizer scope)
POST /v2.1/application/tournaments (List Tournaments)
Edit tournament state (requires application:organizer scope, and signed in user must be an admin of the tournament)
PUT /v2.1/application/tournaments/{tournament_id}/change_state (Change Tournament State)
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 /v2.1/application/tournaments/{tournament_id}/participants (Create Participant)
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 /v2.1/application/tournaments/{tournament_id}/matches/{match_id} (Update Match)
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 (see Authorization)
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 /v2.1/application/tournaments (List Tournaments)
Edit tournament state
PUT /v2.1/application/tournaments/{tournament_id}/change_state (Change Tournament State)
Register participants
POST /v2.1/application/tournaments/{tournament_id}/participants (Create Participant)
Report verified match scores
PUT /v2.1/application/tournaments/{tournament_id}/matches/{match_id} (Update Match)

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.
Players can sign up for tournaments on Challonge.com or in-game and then ultimately play their matches in-game.
Players and spectators can follow tournament results on Challonge.com as they happen in your game.
We’ll help promote your game to tournament organizers on Challonge.com.

How to create a tournament for your game with WebPlay#

As the owner of your Challonge developer application, you have control over who is allowed to connect to your app. Connecting is accomplished in any of these ways:
1.
As the app owner, you can directly assign tournaments on Challonge.com to your application. When creating or editing a tournament, select your application in the “Challonge Connect” portion of the form (https://challonge.com/tournaments/new)
image.png
2.
Use the API. Any tournaments created via the API using the endpoints mentioned above will automatically get connected to your app.
3.
Once you’re publish-ready, you can configure your app to allow tournament organizers on Challonge.com to connect to it.
Once configured, when any Challonge user enters your game title, they’ll be prompted to connect to your game integration. Doing so grants permissions to your app, allowing you to edit the tournament’s state, register participants, and report match scores. As part of the opt-in process, you can require the tournament organizer to define custom metadata, such as accepting rules/policies or settings that are specific to your game like game mode, permitted maps, time limits, etc.

We’re here to help!#

We’d love to help your game realize its full potential, so as you think about adding tournaments to your game, please don’t hesitate to reach out to us (challonge.com/contact).
Modified at 2025-11-05 15:40:27
Previous
About
Next
Connect Request Signing
Built with