Restructure auth documentation

docs/auth/dedi.md

@@ -0,0 +1,49 @@
+---
+position: 1
+---
+# 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](https://www.trackmania.com/player/dedicated-servers). Note that there are some limitations on what you can do with dedicated server tokens (as noted on relevant API endpoint documentation pages).
+
+## Setting up a dedicated server account
+
+A dedicated server account is always bound to a Ubisoft account. Visit [Trackmania.com's dedicated servers page](https://www.trackmania.com/player/dedicated-servers) to create a dedicated server account.
+
+Make sure to store the password after creating your account as it can't be retrieved again later.
+
+Note that your dedicated server account is directly associated to a Ubisoft account - if Nadeo/Ubisoft detect API usage they deem unacceptable, restrictions or bans on your dedicated server account may also have consequences for your associated Ubisoft account.
+
+## Acquiring a Nadeo API access token
+
+Send the following HTTP request using a tool/library of your choice:
+
+```plain
+POST https://prod.trackmania.core.nadeo.online/v2/authentication/token/basic
+
+Headers:
+    Content-Type: application/json
+    Authorization: Basic <login:password (base64-encoded)>
+    User-Agent: <your project/contact information>
+
+Body:
+    { "audience": "NadeoLiveServices" }
+```
+
+The `Authorization` header uses [Basic HTTP authentication](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side) for your dedicated server account credentials (e.g. `username:password` becomes `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`).
+In Go for example, this is done via [SetBasicAuth](https://pkg.go.dev/net/http#Request.SetBasicAuth) - other languages and libraries have their own utility methods for the same purpose.
+
+The body of the request must be a JSON object with the desired audience name. The audience(s) you need depend on the APIs and endpoints you intend to interact with.
+
+| URL                                          | Audience          |
+| -------------------------------------------- | ----------------- |
+| <https://prod.trackmania.core.nadeo.online/>   | NadeoServices     |
+| <https://live-services.trackmania.nadeo.live/> | NadeoLiveServices |
+| <https://meet.trackmania.nadeo.club>           | NadeoLiveServices |
+
+Note that if you don't provide a body, you get a token for the audience `NadeoServices`.
+
+If you plan to interact with API endpoints that require different audiences, you need to request multiple tokens and manage them separately.
+
+## Next steps
+
+The response body contains an `access_token` and a `refresh_token` which you can use for your API requests. See the [token usage guide](/auth/token) for information on how to use and manage tokens.

docs/auth/index.md

@@ -0,0 +1,24 @@
+---
+name: Authentication
+pages:
+  - ubi
+  - dedi
+  - token
+---
+
+# Authentication
+
+This guide explains how to authenticate with Nadeo's APIs. There are 2 available methods:
+
+- [via a dedicated server account](/auth/dedi)
+- [via a Ubisoft account](/auth/ubi)
+
+Dedicated server account authentication is easier to implement but imposes some limitations on what you can access with the API. The relevant restrictions are documented on each of the endpoint documentation pages.
+
+Both authentication paths result in one or more access tokens - see the [token usage guide](/auth/token) for information on how to use and manage them.
+
+For a complete authentication implementation example, you can refer to [Miss' Nadeo Go package](https://github.com/codecat/gonadeo).
+
+## Authentication in Openplanet
+
+If you need to make requests to Nadeo API endpoints from inside an Openplanet plugin, don't handle any of the authentication logic yourself. Instead, use the [NadeoServices dependency](https://openplanet.dev/docs/reference/nadeoservices) as a central authentication plugin.

docs/auth/token.md

@@ -0,0 +1,106 @@
+---
+position: 3
+---
+
+# Using API tokens
+
+This guide explains how to use and manage Nadeo API tokens. See the [authentication overview page](/auth) for information on how to acquire tokens.
+
+If you have already obtained an access token and want to get started, see the [basic usage guide](#using-the-access-token).
+
+To learn how to refresh your tokens without re-authenticating using a Ubisoft account of a dedicated server account, read the [section on refreshing your tokens](#refreshing-your-tokens).
+
+For more detailed information on the tokens' purposes and contents, refer to the [explanations below](#understanding-the-tokens).
+
+## Using the access token
+
+All game APIs require you to send the obtained access token along - the format is always the same.
+
+Simply set the following header on all your requests:
+
+```plain
+Authorization: nadeo_v1 t=<access token>
+```
+
+## Refreshing your tokens
+
+To refresh your tokens (i.e. to obtain a new set of tokens without going through the entire authentication process), send the following HTTP request using a tool/library of your choice:
+
+```plain
+https://prod.trackmania.core.nadeo.online/v2/authentication/token/refresh
+
+Headers:
+    Authorization: nadeo_v1 t=<refresh token>
+```
+
+The response contains new access and refresh tokens.
+
+## Understanding the tokens
+
+There are two types of tokens used by the Nadeo APIs: Access and refresh tokens.
+
+Both are sensitive credentials that can be used maliciously if you share them publicly, so treat them accordingly.
+
+### Access tokens
+
+Access tokens are used in every API request to identify yourself and prove that you are authorized to access that resource.
+
+They are signed [JSON web tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) that you can decode to understand and evaluate their contents (either programmatically or via a client-side decoder such as [JWT.io](https://jwt.io/)).
+
+An access token is always associated with a specific audience (as explained in the authentication methods' documentation pages) which is stored in the token's `aud` payload field.
+
+Access tokens are typically valid for one hour, which you can also verify via the token's `exp` payload field.
+
+See below for the available payload data in a typical access token (using a Ubisoft account access token as an example):
+
+```json
+{
+  "jti": "<uuid>", // token ID
+  "iss": "NadeoServices", // issuer: always "NadeoServices"
+  "iat": 1735394983, // timestamp of issuance
+  "rat": 1735396783, // timestamp of when the token may be refreshed
+  "exp": 1735398583, // timestamp of expiry
+  "aud": "NadeoLiveServices", // audience: either "NadeoServices" or "NadeoLiveServices"
+  "usg": "Client", // usage: either "Client" for a Ubisoft account or "Server" for a dedicated server account
+  "sid": "<uuid>", // session ID
+  "sat": 1735394983, // timestamp of signing, typically equal to "iat"
+  "sub": "5b4d42f4-c2de-407d-b367-cbff3fe817bc", // subject: Nadeo account ID of the authenticated user
+  "aun": "tooInfinite", // display name of the user/dedicated server account
+  "rtk": false, // flag to indicate refresh tokens, always false for access tokens
+  "pce": false, // always false
+  "ubiservices_uid": "a59df3e8-6bff-48a2-98b6-801abf2a298e" // Ubisoft account ID, also known as web identity
+}
+```
+
+### Refresh tokens
+
+Refresh tokens are used to acquire a new set of tokens without going through the entire authentication procedure required for the initial tokens.
+
+They are signed [JSON web tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) that you can decode to understand and evaluate their contents (either programmatically or via a client-side decoder such as [JWT.io](https://jwt.io/)).
+
+A refresh token is always associated with an access token, and using it will yield another access token of the same audience.
+
+Refresh tokens are typically valid for one day, which you can also verify via the token's `exp` payload field.
+
+See below for the available payload data in a typical refresh token (using a Ubisoft account access token as an example):
+
+```json
+{
+  "jti": "<uuid>", // token ID
+  "iss": "NadeoServices", // issuer: always "NadeoServices"
+  "iat": 1735394983, // timestamp of issuance
+  "rat": 1735438183, // timestamp of when the token may be refreshed, not used for refresh tokens
+  "exp": 1735481383, // timestamp of expiry
+  "aud": "NadeoServices", // audience: always "NadeoServices", not to be confused with "refresh_aud"
+  "usg": "Client", // usage: either "Client" for a Ubisoft account or "Server" for a dedicated server account
+  "sid": "<uuid>", // session ID
+  "sat": 1735394983, // timestamp of signing, typically equal to "iat"
+  "sub": "5b4d42f4-c2de-407d-b367-cbff3fe817bc", // subject: Nadeo account ID of the authenticated user
+  "aun": "tooInfinite", // display name of the user/dedicated server account
+  "rtk": true, // flag to indicate refresh tokens, always true for refresh tokens
+  "pce": false, // always false
+  "ubiservices_uid": "a59df3e8-6bff-48a2-98b6-801abf2a298e", // Ubisoft account ID, also known as web identity
+  "refresh_aud": "NadeoLiveServices", // refresh audience, audience for tokens refreshed with this refresh token
+  "limit_type": "none" // always "none"
+}
+```