REST API Authentication

Authorisation to the API happens in two steps. First, using an access key, you need to obtain an access token, then use it to authorise subsequent requests.

Creating an Access Key

The access key is a pair of a private and a public key. You generate them, for example, with the openssl tool:

openssl ecparam -name prime256v1 -genkey -noout -out private.pem
openssl ec -in private.pem -pubout > public.pem

This creates two files, private.pem and public.pem. The first contains the private key, which must be kept secure.

The second contains the public key, which must be added to the user settings in TOPlist Profi.

Getting the Access Token

To obtain the access token, send a request to https://profi.toplist.eu/api/v1/login. Authentication is done via the HTTP Authorization header, which must contain a JWT signed with the private key. Example call in Python:

import jwt
import requests
import time

privateKey = open('private.pem').read()
jwtPayload = jwt.encode({
    'sub': 'user@example.com',
    'aud': 'batch',
    'iss': '0123456-789a-bcde-f012-3456789abcd',
    'nbf': int(time.time()),
    'exp': int(time.time()) + 5*60,
    'jti': '1234567890'
}, privateKey, algorithm='ES256')

token = requests.post("https://profi.toplist.eu/api/v1/login",
    headers={
        'Accept': 'application/json',
        'Authorization': jwtPayload
    }
).json()['token']

Meaning of the JWT claims:

• sub — email of the user the token is created for
• aud — in this case always the value 'batch'
• iss — identifier of the Operator, as listed in the server settings
• nbf — time when the token starts being valid
• exp — time when the token stops being valid (maximum 1 hour)
• jti — unique token identifier

Using the Token

The generated token must be added to the Authorization header as a Bearer token for every subsequent request, i.e.:

Authorization: Bearer <token>

↓ Download this page as Markdown