Introduction
The Toornament API uses the OAuth 2 protocol to handle the authorization to access its resources. OAuth 2 is an authorization protocol that enables applications to obtain a limited access to user data on an HTTP service. It is notably used by Google, Twitter or Amazon. It provides several authorization flows for web, desktop and mobile applications. For more information about OAuth 2, please refer to oauth.net.
Warning: The client_id and client_secret of your application are sensible data that function like a login and a password for your application. They should be kept private in a secure storage.
Authorization Flows
The Toornament API currently supports the following authorization flows (also called grant types):
- Client Credentials allows your server application to access your own data.
- Authorization Code allows your server application to request access to the data of another user.
Client Credentials Flow
This flow allows an application to access its own private data. The private data of an application designates the private data of the application's owner.

Step 1 : Your application requests access to Toornament.
An access request is sent to the Toornament OAuth 2 server with your application's credentials and the authorization scopes (see scopes documentation). This request is sent from your application using a POST method:
RequestPOST https://api.toornament.com/oauth/v2/token
The following parameters must be included in the request body using the "application/x-www-form-urlencoded" content type:
Request body (with line breaks and spaces for readability)grant_type=client_credentials& client_id={client_id}& client_secret={client_secret}& scope={scope}
client_id
is your application's client idclient_secret
is your application's client secretscope
is the space-delimited list of requested permissions (list of scopes)
Step 2 : Toornament verifies the credentials and returns an access token
If the authorization is accepted, the Toornament OAuth 2 server will return a json object with an access token. It has a limited duration (~25 hours). It can be stored in a database but you should then ensure it is securely stored using encryption.
Response{ "access_token": "TUzZDcxYWQxZmYwNTU0ZTg2M2MyMDk5ZmUyZWI2ZQ", "expires_in": 90000, "token_type": "Bearer" }
access_token
is a JSON Web Token signed with the Toornament API private keyexpires_in
is an integer representing the Time-to-live (in seconds) of the access tokentoken_type
isBearer
Once a token has expired, you must obtain a new token by starting step 1 again.
Step 3 : Your application uses the access token to call the Toornament APIs.
Your application must provide the access token every time it is calling the Toornament API using the
Authorization
HTTP header.
GET /endpoint HTTP/1.1 Host: api.toornament.com X-Api-Key: {api-key} ... Authorization: Bearer {access-token}
Authorization Code Flow
This flow allows an application to access private data of another user. This implies that the application asks the user the permission to access some of his private data. This flow requires the user to be present and to consent.

Step 1 : Your application sends the user to Toornament to grant access.
When your application requires access to user data, it starts the authorization process. You application sends the user to the Toornament OAuth 2 server with an access request that describes the permissions you need.
Redirect or link (with line breaks and spaces for readability)https://account.toornament.com/oauth2/authorize? response_type=code& client_id={client_id}& redirect_uri={redirect_uri}& scope={scope}& state={state}
client_id
is your application's client idredirect_uri
is the redirect uri configured in your applicationscope
is the space-delimited list of requested permissions (list of scopes)state
is a unique hash that serves as a CSRF token
Warning: the state property must contain a CSRF token to ensure that your authorization process is protected against CSRF attacks. You should store this value in the user session to be validated when the user returns on your application.
Step 2: Toornament asks the user to login and to consent.
If the user is not logged in, he is prompted to log in or to create a new Toornament account. Once logged, the user decides whether to grant your application the requested access. Toornament displays a consent screen that shows the name of your application and a list of requested scopes. The user can then accept or refuse to grant access to your application.
Step 3: Toornament sends the user back to your specified URI.
If the user has accepted : he will be redirected to the redirect_uri
with query
string parameters containing an authorization code
and the state
property.
https://{your-application-redirect-uri}? code={code}& state={state}
code
is an authorization codestate
is the unique hash that serves as a CSRF token
Warning: Your must validate the CSRF token provided in the state property to ensure that step 1 was not compromised by a CSRF attack.
If the user has refused : he will be re-directed to the redirect_uri
without the
code
property.
https://{your-application-redirect-uri}?
state={state}
state
is the unique hash that serves as a CSRF token
Step 4: Your application requests access to Toornament.
Once your application has received an authorization code, you must exchange it for an access token and a refresh token. This request is sent from your application using a POST method:
RequestPOST https://api.toornament.com/oauth/v2/token
The following parameters must be included in the request body using the "application/x-www-form-urlencoded" content type:
Request body (with line breaks and spaces for readability)grant_type=authorization_code& client_id={client_id}& client_secret={client_secret}& redirect_uri={redirect_uri}& code={code}
client_id
is your application's client idclient_secret
is your application's client secretredirect_uri
is the redirect uri configured in your applicationcode
is the authorization code
Once the authorization code has been consumed, it is no longer usable. It also expires after a few minutes for security reasons.
Step 5: Toornament returns refresh and access tokens.
If the authorization is accepted, the Toornament OAuth 2 server will return a json object with both an access token and a refresh token. The access token has a limited duration (~25 hours). The refresh token has a longer duration (14 days). Both keys can be stored in a database but you should then ensure it is securely stored using encryption. The refresh token may be used to re-generate new access tokens once they are expired (see Refresh token).
Response{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjFiYzE3YzY2NDIxZmZmMWRlODU5M", "expires_in": 90000, "token_type": "Bearer", "refresh_token": "B6wdWAr0aTsih2hHpikAeS6gXAOo2fY_7z8u1aLuLEhVlQ2XULpiDfy3SR5jGb_ozCv", }
access_token
is a JSON Web Token signed with the Toornament API private keyexpires_in
is an integer representing the Time-to-live (in seconds) of the access tokentoken_type
isBearer
refresh_token
is an encrypted payload that can be used to re-generate a new access token
Step 6 : Your application uses the access token to call the Toornament APIs.
Your application must provide the access token every time it is calling the Toornament API using the
Authorization
HTTP header.
GET /endpoint HTTP/1.1 Host: api.toornament.com X-Api-Key: {api-key} ... Authorization: Bearer {access-token}
How to refresh your access token?
When an access token has expired, you can use a refresh token to request a new one.
RequestPOST https://api.toornament.com/oauth/v2/token
The following parameters must be included in the request body using the "application/x-www-form-urlencoded" content type:
Request body (with line breaks and spaces for readability)grant_type=refresh_token& client_id={client_id}& client_secret={client_secret}& refresh_token={refresh_token}
client_id
is your application's client idclient_secret
is your application's client secretrefresh_token
is the refresh token previously acquired
The server will return new access and refresh tokens. The previous access and refresh tokens will be invalidated and should be replaced by the new ones.
Response{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjFiYzE3YzY2NDIxZmZmMWRlODU5M", "expires_in": 90000, "token_type": "Bearer", "refresh_token": "B6wdWAr0aTsih2hHpikAeS6gXAOo2fY_7z8u1aLuLEhVlQ2XULpiDfy3SR5jGb_ozCv", }
access_token
is a JSON Web Token signed with the Toornament API private keyexpires_in
is an integer represents the TTL of the access tokentoken_type
isBearer
refresh_token
is an encrypted payload that can be used to re-generate a new access token