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.

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

require 'httparty'

DOMAIN        = "[challonge.com](<http://challonge.com/>)"
CLIENT_ID     = "your-client-id-here"
CLIENT_SECRET = "your-client-secret-here"
REDIRECT_URI  = "[<https://auth.advancedrestclient.com/oauth-popup.html>](<https://auth.advancedrestclient.com/oauth-popup.html>)" # for debugging, it just displays the resulting code
VERIFY_SSL    = true

################################################################################

OAUTH_ROOT_URL = "[<https://api>](<https://api/>).#{DOMAIN}"
API_ROOT_URL   = "[<https://api>](<https://api/>).#{DOMAIN}/v2"

# Request an auth code
puts "Authorize link: " + URI.escape("[<https://api>](<https://api/>).#{DOMAIN}/oauth/authorize?client_id=#{CLIENT_ID}&redirect_uri=#{REDIRECT_URI}&response_type=code&scope=me+tournaments:read+tournaments:write+matches:read+matches:write+participants:read+participants:write")
print "Code: "
code = gets.chomp

# Request tokens
response = HTTParty.post(
  "#{OAUTH_ROOT_URL}/oauth/token",
  body: URI.encode_www_form({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: "authorization_code",
    code: code,
    redirect_uri: REDIRECT_URI
  }),
  headers: {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  verify: VERIFY_SSL
)

refresh_token = response["refresh_token"]
puts "Access token: #{response["access_token"]}"
puts "Refresh token: #{refresh_token}"

# Request new tokens using the refresh token
response = HTTParty.post(
  "#{OAUTH_ROOT_URL}/oauth/token",
  body: URI.encode_www_form({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: "refresh_token",
    refresh_token: refresh_token,
    redirect_uri: REDIRECT_URI
  }),
  headers: {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  verify: VERIFY_SSL
)

puts "New access token: #{response["access_token"]}"
puts "New refresh token (optional, the old one still works): #{response["refresh_token"]}"

2. Device Authorization Grant Flow

<aside> 💡 Use case: for games or apps on platforms without web browsers or keyboards; gain authorization from Challonge users to make requests on their behalf

</aside>

Postman documentation: https://documenter.getpostman.com/view/11915787/U16jN6TK#3d1082d9-c237-4cef-aae3-49c877681228 (NOTE: this flow hits connect.challonge.com instead of api.challonge.com)

Examples: get a player's Challonge ID to validate their inclusion in a tournament, check a player in to a tournament, filter your in-game tournament list by those organized by the authenticated player