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.
<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"]}"
<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