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 function like a login and a password for your application. They should be kept private in a secure storage.

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

{
    "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.

GET /endpoint HTTP/1.1
Host: api.toornament.com
X-Api-Key: {api-key}
...
Authorization: Bearer {access-token}