OAuth 2

What is OAuth 2 ?

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 Facebook, Google, or Github. It provides several authorization flows for web, desktop and mobile applications. For more information about OAuth 2, please refer to the RFC 6749.

For the moment, we only support a single authorization flow called "client credentials" which allows authenticating the owner of the application and accessing its own private data.

To use OAuth 2, you'll need a client_id and a client_secret. You can obtain these by creating an application. After registering your application, you will find the client id and client secret on the profile of your application.

Note: The client_id and client_secret are sensitive data that function like a login and password. They should be kept private and not made publicly available.

Authenticate with OAuth 2

To authenticate using OAuth 2, you must use the client credentials workflow. This workflow requires you to contact the authorization server in order to obtain an access token. This access token can then be used to perform calls on the API authenticated as the application's owner.

  1. The application authenticates with the authorization server and requests an access token.
  2. The authorization server authenticates the application, and if valid returns an access token.
  3. The application uses the access token when calling the API.

The access token has a limited duration (~25 hours). It can be stored in a database to avoid multiple authentication calls but you should ensure it is securely stored using encryption. Once expired, the application can request a new access token.

Requesting an access token

To obtain an access token, you must call the authorization server and request an access token for the application. This is performing by calling the OAuth 2 token endpoint. You may find more information about obtaining an access token on the OAuth 2 Token endpoint documentation.

Using an access token

Once you have obtained an OAuth 2 access token, you must use it on each API call.

Adding the "Authorization" HTTP header. It avoids leaking the token when an URL is copy-pasted or leaving the token visible in server logs. However, we also provide the query parameter method to facilitate your application's development.

HTTP header

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