Welcome to WU24 Tivoli API platform!

This documentation is for teams who want to integrate their mini-games into the Tivoli system. Once your game is connected, users will be able to launch it from Tivoli and send gameplay data (like wins) securely back to our backend.

Requirements Before You Start

Before you can connect your game:

You must request an API Key from the Tivoli backend team (this key is unique to your group).
Your game must be able to:
- Accept a JWT token from the frontend.
- Send authenticated requests back to our API using both:
  - A valid JWT (from the user)
  - Your API Key

Understanding the JWT Token

A JSON Web Token is a secure and compact token used to verify the identity of a user.

Purpose

In the Tivoli system, the JWT token ensures that the player interacting with your game is logged in and authorised to play. It must be included with every request your game sends to the Tivoli API.

How It’s Created

The JWT is created by the Tivoli backend when the user logs in at tivoli.se.
The token contains digitally signed data (e.g. user ID, expiration time, etc.).
Your game does not need to parse or validate the token — only attach it in requests.

Authentication Rules

A JWT token is required for all user-specific requests, such as reporting a win.
An API key is required for all authenticated group-level requests (these are not used by regular users).
Some endpoints are publicly accessible, such as viewing an amusement via an embedded iframe.

Receiving the JWT (User Login)

When a player launches your game via the tivoli, they will be authenticated, and a JWT token will be passed to your game. Your game must read this token and store it for use in API requests to Tivoli. Otherwise the player can’t be identified and no transaction can go through.

Using the Tivoli API

Required Headers for All Requests

To interact with our backend, your game must include two headers in every request:

(Here we will add our backend code for the test game, making it easy for our fellow classmates to connect.)

If either of the required headers is missing, the request will be rejected by the Tivoli API. While the API returns error responses, it is your responsibility to handle these gracefully and display appropriate error messages within your game.

Test Account

Email: rune@yrgobanken.vip

Password: password

Yaml

here you can download the yaml file to see all the API endpoints!