Authorization

  • API v2.0
  • Security

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

Request
POST 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 id
  • client_secret is your application's client secret
  • scope 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 key
  • expires_in is an integer representing the Time-to-live (in seconds) of the access token
  • token_type is Bearer

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.

Request
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 id
  • redirect_uri is the redirect uri configured in your application
  • scope 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.

Redirect (with line breaks and spaces for readability)
https://{your-application-redirect-uri}?
 code={code}&
 state={state}
  • code is an authorization code
  • state 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.

Redirect (with line breaks and spaces for readability)
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:

Request
POST 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 id
  • client_secret is your application's client secret
  • redirect_uri is the redirect uri configured in your application
  • code 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 key
  • expires_in is an integer representing the Time-to-live (in seconds) of the access token
  • token_type is Bearer
  • 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.

Request
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.

Request
POST 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 id
  • client_secret is your application's client secret
  • refresh_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 key
  • expires_in is an integer represents the TTL of the access token
  • token_type is Bearer
  • refresh_token is an encrypted payload that can be used to re-generate a new access token