Skip to content

Instantly share code, notes, and snippets.

@codecat
Last active May 28, 2022
Embed
What would you like to do?
Trackmania Webservices

Authentication setup

This guide will explain how to authenticate with Nadeo's API. There are 2 methods of doing so, one is via a Ubisoft account, and one is via a dedicated server account. Note that the dedicated server account way is easier but imposes some limitations on what you can access with the API, but it could be enough.

Refer to my Nadeo Go package for a complete example.

With a Ubisoft account

Send a POST request to the following URL:

https://public-ubiservices.ubi.com/v3/profiles/sessions

With the following request headers:

Content-Type: application/json
Ubi-AppId: 86263886-327a-4328-ac69-527f0d20a237
Authorization: Basic ...

Where the Authorization header is a basic authorization of your Ubisoft email and password. (In Go for example, this is via SetBasicAuth)

Also, make sure you pass a valid user agent that Ubisoft can understand. Ubisoft blocks certain default user agents, so make sure you pass your own. Include your project name and a way to contact you. (This counts not only for the Ubisoft API, but also Nadeo's API.) For example:

User-Agent: My amazing app / my.email.address@example.com

The response will contain a Ubisoft authentication ticket that you can use for Nadeo's Ubiservices authentication endpoint. So, send a POST request to the following URL:

https://prod.trackmania.core.nadeo.online/v2/authentication/token/ubiservices

With the following request headers:

Content-Type: application/json
Authorization: ubi_v1 t=<full ubi token>

Where Authorization has your Ubisoft account ticket right after t=. You also have to provide a request body, which is described below in Authorization body.

With a dedicated server account

If you don't want to or can't use a Ubisoft account for authentication, you can use a dedicated server account. Note that there are some limitations on what you can do with dedicated server tokens.

Send a POST request to the following URL:

https://prod.trackmania.core.nadeo.online/v2/authentication/token/basic

With the following request headers:

Content-Type: application/json
Authorization: Basic ...

Where the Authorization header is a basic authorization of your dedicated server account. (In Go for example, this is via SetBasicAuth)

Authorization body

For both authentication methods described above, you have to provide a body telling the API what to authenticate with. The body of the request must be a Json object with the desired audience name:

{"audience":"NadeoLiveServices"}

Note that if you don't provide a json body, you get a token for audience NadeoServices. You may also request a token for the audience NadeoClubServices.

This will give you a JSON web token together with a refresh token:

{
	"accessToken":"eyJhbGciOiJIUzI1NiIsImVudiI6InRyYWNrbWFuaWEtcHJvZCIsInZlciI6IjEifQ.<payload>.<signature>",
	"refreshToken":"eyJhbGciOiJIUzI1NiIsImVudiI6InRyYWNrbWFuaWEtcHJvZCIsInZlciI6IjEifQ.<payload>.<signature>"
}

If you URL-base64-decode the payload, you get the following json object:

{
	"jti":"<uuid>",
	"iss":"NadeoServices",
	"iat":1595191016,
	"rat":1595192816,
	"exp":1595194616,
	"aud":"NadeoLiveServices",
	"usg":"Server",
	"sid":"<uuid>",
	"sub":"<uuod>",
	"aun":"mm",
	"rtk":false,
	"pce":false
}

Where exp defines the expiration time, and rat the time after which you are able to refresh the token.

Token refreshing

To refresh your token, send a POST to the following URL:

https://prod.trackmania.core.nadeo.online/v2/authentication/token/refresh

With the Authorization header set to nadeo_v1 t=<full refresh token>.

The response is the same as with normal authentication.

Live services requests

To send requests to the live services, you simply have to add the header Authorization to every request with the value nadeo_v1 t=<access token>.

For example, to get a list of the tracks currently in track of the day, you could run this curl command:

curl -H "Authorization: nadeo_v1 t=<access token>" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     https://live-services.trackmania.nadeo.live/api/token/campaign/month?offset=0&length=9

Base URL's and audiences

The API's base URL's and their necessary audiences are:

URL Audience
https://prod.trackmania.core.nadeo.online/ NadeoServices
https://live-services.trackmania.nadeo.live/ NadeoLiveServices
https://club.trackmania.nadeo.club NadeoClubServices
https://competition.trackmania.nadeo.club NadeoClubServices
https://matchmaking.trackmania.nadeo.club NadeoClubServices

Finding routes

You can use Openplanet to inspect HTTP requests sent from scripts and find out more about the live services API. I have made this plugin specifically for that purpose.

Openplanet can also be used to extract the game's scripts, which describe everything in the API as well in code form. These scripts are located in Scripts/Libs/Nadeo/TMNext/TrackMania/API/ of the Trackmania titlepack.

You may also access any of the core API functions, listed here. These require the NadeoServices audience. There's no documentation for them, unless you disassemble the game and find out for yourself. Guessing might also work.

Further help

If you need any further help, the Openplanet Discord is a great place to ask.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment