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.

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:

image.png

OAuth Flows

1. Authorization Code Flow

<aside> 💡 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.

</aside>

Postman documentation: https://documenter.getpostman.com/view/11915787/U16jN6TK#4fd12082-16bb-42af-b0bb-028c8f822d83

Examples: getting a list of tournaments a user has organized, registering for a tournament on behalf of a user, creating a tournament on behalf of a user.

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"):