Authorization

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 functions 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 the access to 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:

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:

grant_type=client_credentials&
 client_id={client_id}&
 client_secret={client_secret}&
 scope={scope}

• client_id with your application's client id
• client_secret with your application's client secret
• scope containing a 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.

{
    "access_token": "TUzZDcxYWQxZmYwNTU0ZTg2M2MyMDk5ZmUyZWI2ZQ",
    "expires_in": 90000,
    "token_type": "Bearer"
}

• access_token with a JWT signed with the Toornament API private key
• expires_in with an integer represents the TTL of the access token
• token_type with the value 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 each 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.

https://account.toornament.com/oauth2/authorize?
 response_type=code&
 client_id={client_id}&
 redirect_uri={redirect_uri}&
 scope={scope}&
 state={state}

• client_id with your application's client id
• redirect_uri with the redirect uri configured in your application
• scope containing a space-delimited list of requested permissions (list of scopes)
• state with 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 containing an authorization code
• state with 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 with 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:

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:

grant_type=authorization_code&
 client_id={client_id}&
 client_secret={client_secret}&
 redirect_uri={redirect_uri}&
 code={code}

• client_id with your application's client id
• client_secret with your application's client secret
• redirect_uri with the redirect uri configured in your application
• code containing 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).

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjFiYzE3YzY2NDIxZmZmMWRlODU5M",
    "expires_in": 90000,
    "token_type": "Bearer",
    "refresh_token": "B6wdWAr0aTsih2hHpikAeS6gXAOo2fY_7z8u1aLuLEhVlQ2XULpiDfy3SR5jGb_ozCv",
}

• access_token with a JWT signed with the Toornament API private key
• expires_in with an integer represents the TTL of the access token
• token_type with the value Bearer
• refresh_token with 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 each 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.

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:

grant_type=refresh_token&
 client_id={client_id}&
 client_secret={client_secret}&
 refresh_token={refresh_token}

• client_id with your application's client id
• client_secret with your application's client secret
• refresh_token with the refresh token you acquired earlier

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.

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjFiYzE3YzY2NDIxZmZmMWRlODU5M",
    "expires_in": 90000,
    "token_type": "Bearer",
    "refresh_token": "B6wdWAr0aTsih2hHpikAeS6gXAOo2fY_7z8u1aLuLEhVlQ2XULpiDfy3SR5jGb_ozCv",
}

• access_token with a JWT signed with the Toornament API private key
• expires_in with an integer represents the TTL of the access token
• token_type with the value Bearer
• refresh_token with an encrypted payload that can be used to re-generate a new access token