A big change from version 1 of our API is the addition of OAuth. This allows you to build an application that can perform actions on behalf of a Challonge user. You can fetch their tournaments, create tournaments on their behalf, report scores for them, etc. Best of all, we support OAuth flows that accommodate just about any application.

Option 1: OAuth

Once you optain an access token using one of the OAuth flows below, use the following headers with your API requests:

Option 2: API v1 Key

If you’re migrating from API v1 or only need authorization on behalf of your own account, you can consider using an API v1 key. To issue an APIv1 key, go to https://challonge.com/settings/developer

For v1 authorization, set the Authorization-Type header to v1, and the Authorization header to your APIv1 key:

OAuth Flows

1. Authorization Code Flow

grant_type = "authorization_code"

The OAuth authorization code flow is a secure method for a client application to access a user's protected resources by first getting an authorization code and then exchanging it for an access token. This allows you to perform actions on behalf of another user (e.g. create a tournament with the user as the organizer).

💡 Use case: for websites or apps on platforms with web browsers - gain authorization from Challonge users to make requests on their behalf. This is akin to signing in to a service with Facebook or Discord.

The following diagram illustrates the OAuth Authorization Code Flow with Challonge:

+--------+                                           +---------------+
|        |--(A)------- Authorization Grant --------->|               |
|        |                                           |               |
|        |<-(B)----------- Access Token -------------|               |
|        |               & Refresh Token             |               |
|        |                                           |               |
|        |                            +----------+   |               |
|        |--(C)---- Access Token ---->|          |   |               |
|        |                            |          |   |               |
| Your   |<-(D)- Protected Resource --| Challonge|   |  Challonge    |
| Server |                            | Resource |   |  Auth Server  |
|        |--(E)---- Access Token ---->| Server   |   |               |
|        |                            |          |   |               |
|        |<-(F)- Invalid Token Error -|          |   |               |
|        |                            +----------+   |               |
|        |                                           |               |
|        |--(G)----------- Refresh Token ----------->|               |
|        |                                           |               |
|        |<-(H)----------- Access Token -------------|               |
+--------+           & Optional Refresh Token        +---------------+

Challonge access tokens have a 1-week expiration, but refresh tokens are supported. After authorizing with OAuth (/oauth/authorize) and getting a code, use that code to request a token (/oauth/token). The token response will include both an access token and a refresh token similar to this format:

{
  "access_token"=>"accesstokenhere",
  "token_type"=>"Bearer",
  "expires_in"=>604800,
  "refresh_token"=>"refreshtokenhere",
  "scope"=>"me tournaments:read tournaments:write matches:read matches:write participants:read participants:write",
  "created_at"=>1623246724
}

So, you'll need to store both tokens to avoid having to authorize again. Once your access token fails, you can use the refresh token to get a new access token (/oauth/token with these params: {"grant_type": "refresh_token", refresh_token: "your_refresh_token"}).

The following Ruby script demonstrates how to authorize, request tokens (grant type "authorization_code"), and request new tokens using a refresh token (grant type "refresh_token"):

2. Device Authorization Grant Flow

grant_type = "device_code"

The OAuth device authorization grant (formerly known as the Device Flow) is an OAuth 2.0 extension that enables devices with no browser or limited input capability to obtain an access token. This is commonly seen on TV apps.

💡 Use case: for a video game or physical console like an electronic dart board, prompt the user to scan a QR code to have them sign in to Challonge from their phone. Once signed in and authorized to share access to your app, make API requests on their behalf to populate UIs within your system.

This flow involves requesting a device code and polling for an access token while waiting for the user to authenticate from a phone or PC. Here's an in-game example that illustrates the process:

Once the user signs in from their phone or other web browser, your game is issued an access token for that user. As shown below, the game gets an access token and displays the user’s information. The game UI can then show the user’s tournaments, allow them to start tournaments, and even automatically report scores to facilitate the tournaments.

3. Client Credentials Flow

Examples:

Manage tournaments organized by the application's owner or a community owned by the application's owner.

Fetch all tournaments created by users of your application (created via the Authorization Code flow above), publish validated match results for your game.

With OAuth, once someone gives you permission to create tournaments on their behalf, you'll likely want a way to aggregate all of those tournaments. A common use case is in a game. Imagine you created a Challonge developer application for use in the game. Users can create tournaments in-game once they complete OAuth with your developer application. While these tournaments will all have different organizers, they maintain a link to your developer application. If you want to list all of these tournaments in-game, you'll need to use the client credentials flow to gain access to application-scoped API routes (e.g. /application/tournaments.json).

Authorization

Option 1: OAuth#

Option 2: API v1 Key#

OAuth Flows#

1. Authorization Code Flow#