# REST API Authentication

**Source:** <https://about.toplist.eu/documentation/api-authentication/>  
**Retrieved:** 2026-11-06

---

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

```bash
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](https://profi.toplist.eu/#user_setting).

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

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

---

© 1997 - 2026 TOPlist