DriversHub

API-Dokumentation

Repository: CharlesWithC/HubBackend

1. API-Grundlagen

Base URL

Die API besitzt keine fest eingebaute öffentliche Base URL. Host und API-Prefix kommen aus der Hub-Konfiguration.

Beispielkonfiguration:

{
  "domain": "hub.example.com",
  "prefix": "/api"
}

Damit lautet die Base URL:

https://hub.example.com/api

Ein Request auf:

GET /user/profile

wird also beispielsweise:

GET https://hub.example.com/api/user/profile

Der Prefix ist konfigurierbar und muss mit / beginnen.

Swagger / OpenAPI

Wenn in der Konfiguration

{
  "openapi": true
}

gesetzt wird, stellt der Server die interaktive Swagger-Dokumentation unter

{prefix}/doc

bereit.

Bei prefix: "/api" also:

https://hub.example.com/api/doc

Im Repository liegt außerdem:

/openapi.json

---

2. Authentifizierung

Es gibt zwei Token-Typen:

1. Bearer Token – für Benutzer
2. Application Token – für Anwendungen/Integrationen

Bearer Token

Header:

Authorization: Bearer <TOKEN>

Beispiel:

curl \
  -H "Authorization: Bearer e1234567-89ab-cdef-0123-456789abcdef" \
  https://hub.example.com/api/user/profile

Tokens sind UUID-artige, serverseitig gespeicherte Session-Tokens. Es steckt kein JWT-Payload darin.

Application Token

Header:

Authorization: Application <TOKEN>

Beispiel:

curl \
  -H "Authorization: Application 12345678-1234-1234-1234-123456789abc" \
  https://hub.example.com/api/user/profile

Application Tokens haben gegenüber normalen User-Tokens Einschränkungen. Nicht jeder authentifizierte Endpoint muss Application Tokens akzeptieren.

---

3. Allgemeine Request-Regeln

Für praktisch alle Requests außer GET erwartet das Backend:

Content-Type: application/json

Ausnahmen sind insbesondere Tracker-Webhooks:

/tracksim/*
/trucky/*
/custom-tracker/*
/unitracker/*

Diese dürfen tracker-spezifische Payloads verwenden.

Standard-JSON-Request:

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe"}' \
  "$BASE/user/profile"

Fehlerformat

FastAPI-/HTTP-Fehler werden grundsätzlich in dieser Art zurückgegeben:

{
  "error": "Fehlermeldung"
}

Typische Statuscodes sind:

400  Bad Request
401  Unauthorized
403  Forbidden
404  Not Found
409  Conflict
422  Unprocessable Entity
423  Locked
428  Precondition Required
429  Too Many Requests
500  Internal Server Error
503  Service Unavailable

Bei Request-Validation wird die normale ausführliche FastAPI-422-Antwort durch:

{
  "error": "Unprocessable Entity"
}

ersetzt.

---

4. Rate Limits

Es gibt globale und endpoint-spezifische Rate Limits.

Global:

300 Requests / 60 Sekunden

Nach Überschreiten kann der Client für etwa fünf Minuten global blockiert werden.

Zusätzlich besitzen einzelne Endpoints eigene Limits.

Beispiel aus /auth/password:

3 Requests / 60 Sekunden

---

5. Benutzer-IDs: uid vs. userid

Das ist für Clients besonders wichtig.

uid

Interne, eindeutige User-ID.

Jeder Account besitzt eine uid.

userid

Mitglieds-/Driver-Hub-ID.

Diese existiert erst sinnvoll, nachdem ein Account als Mitglied angenommen wurde.

Daher können APIs je nach Einsatzzweck entweder:

uid

oder

userid

verlangen.

---

6. Login und Authentifizierungsflow

POST /auth/password

Login mit E-Mail und Passwort.

Body

{
  "email": "user@example.com",
  "password": "Secret123!",
  "captcha-response": "<captcha-token>"
}

captcha-response sollte als erforderlich betrachtet werden, auch wenn die OpenAPI-Datei es nicht sauber als required kennzeichnet.

Unterstützte Captcha-Systeme:

Cloudflare Turnstile
hCaptcha

Erfolgreicher Login ohne MFA

{
  "token": "e....",
  "mfa": false
}

Login mit aktiviertem MFA

{
  "token": "f....",
  "mfa": true
}

Der zurückgegebene Token ist in diesem Fall zunächst ein temporäres Auth-Ticket.

Danach:

POST /auth/mfa

Body:

{
  "token": "<temporary-auth-ticket>",
  "otp": "123456"
}

Danach erhält man den eigentlichen Session-Token.

---

POST /auth/register

Registriert einen Account per E-Mail/Passwort.

Body:

{
  "email": "user@example.com",
  "password": "Secret123!",
  "captcha-response": "<captcha-token>"
}

Das Passwort muss mindestens acht Zeichen lang sein. Die konkrete Prüfung berücksichtigt außerdem Groß-/Kleinbuchstaben, Zahlen und Sonderzeichen.

Eine funktionierende SMTP-Konfiguration ist für die E-Mail-Bestätigung notwendig.

Bei Erfolg wird bereits ein Session-Token ausgegeben:

{
  "token": "e....",
  "mfa": false
}

---

POST /auth/reset

Startet einen Password-Reset.

{
  "email": "user@example.com",
  "captcha-response": "<captcha-token>"
}

---

POST /auth/email

Verarbeitet E-Mail-Bestätigungs-/Reset-Links.

Query:

?secret=<SECRET>

Bei Password-Reset ggf. Body:

{
  "password": "NewSecret123!"
}

---

Discord / Steam Login

GET /auth/discord/callback

Queryparameter:

code
error_description
callback_url

callback_url ist erforderlich.

GET /auth/steam/callback

Steam-OpenID-Callback.

Die von Steam gelieferten Parameter müssen an diesen Endpoint weitergereicht werden.

---

7. Token API

Method	Endpoint	Funktion
GET	/token	aktuellen Token validieren
PATCH	/token	aktuellen Token erneuern
DELETE	/token	aktuellen Token widerrufen
GET	/token/list	Sessions/Tokens auflisten
DELETE	/token/hash	bestimmten Token anhand Hash widerrufen
DELETE	/token/all	alle Benutzer-Tokens widerrufen
GET	/token/application/list	Application Tokens auflisten
POST	/token/application	Application Token erzeugen
DELETE	/token/application	Application Token widerrufen
DELETE	/token/application/all	alle Application Tokens widerrufen
POST	/auth/ticket	Auth-Ticket erzeugen/verwenden
GET	/auth/ticket	Auth-Ticket abrufen

Beispiel Token-Validierung:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/token"

Tokenliste unterstützt unter anderem:

page
page_size
order_by
order

Mögliche order_by-Werte laut OpenAPI:

ip
timestamp
country_code
user_agent
last_used_timestamp

---

8. System-/Info-API

Method	Endpoint	Funktion
GET	/	Drivers-Hub-Informationen
GET	/status	Serverstatus
POST	/status/database/restart	Datenbankverbindung neu starten
GET	/languages	Hub- und unterstützte Sprachen
POST	/discord/role-connection/enable	Discord Role Connection aktivieren
POST	/discord/role-connection/disable	Discord Role Connection deaktivieren
GET	/config	Konfiguration lesen
PATCH	/config	Konfiguration ändern
POST	/config/reload	Konfiguration neu laden
POST	/restart	Backend neu starten
GET	/audit/list	Audit-Log abrufen

Administrative Endpoints sind entsprechend permission-geschützt.

---

9. User API

Profile und Benutzer

Method	Endpoint	Funktion
GET	/user/list	Benutzerliste
GET	/user/profile	Userprofil abrufen
PATCH	/user/profile	Name/Avatar ändern
PATCH	/user/bio	Bio ändern
PATCH	/user/activity	Aktivitätsdaten ändern
PATCH	/user/{uid}/note	persönliche Notiz über User
PATCH	/user/{uid}/note/global	globale Staff-Notiz
POST	/user/tracker/switch	aktiven Tracker wechseln

GET /user/profile

Kann einen Benutzer anhand verschiedener IDs suchen:

userid
uid
discordid
steamid
truckersmpid
email

Zusätzliche Parameter:

role_history_limit
ban_history_limit

Ohne Ziel-ID wird typischerweise das eigene Profil verwendet.

Beispiel:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile?uid=123"

Oder:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile?discordid=123456789012345678"

PATCH /user/profile

Body:

{
  "name": "New Name",
  "avatar": "https://example.com/avatar.png"
}

Optionale Queryparameter:

uid
sync_from_discord
sync_from_steam
sync_from_truckersmp

Damit können Profildaten auch von verbundenen Plattformen synchronisiert werden.

---

10. Sprache, Zeitzone und Privacy

Method	Endpoint	Funktion
GET	/user/language	aktuelle Sprache
PATCH	/user/language	Sprache ändern
GET	/user/timezone	Zeitzone lesen
PATCH	/user/timezone	Zeitzone ändern
GET	/user/privacy	Privacy-Einstellungen
PATCH	/user/privacy	Privacy-Einstellungen ändern

---

11. Password und MFA

Method	Endpoint	Funktion
PATCH	/user/password	Passwort ändern
POST	/user/password/disable	Password-Login deaktivieren
POST	/user/mfa/enable	TOTP-MFA aktivieren
POST	/user/mfa/disable	MFA deaktivieren

TOTP-MFA wird bei jedem Login verwendet.

Für besonders kritische administrative Aktionen, insbesondere Config-Reload, kann MFA verpflichtend sein.

---

12. User Connections

Method	Endpoint	Funktion
POST	/user/resend-confirmation	Bestätigungsmail erneut senden
PATCH	/user/email	E-Mail verbinden/ändern
PATCH	/user/discord	Discord verbinden
PATCH	/user/steam	Steam verbinden
PATCH	/user/truckersmp	TruckersMP verbinden
PATCH	/user/{uid}/connections	Connections administrativ ändern
DELETE	/user/{uid}/connections/{connection}	Connection entfernen

Für das Job-Tracking ist insbesondere eine verbundene Steam-ID relevant.

---

13. Notifications

Method	Endpoint	Funktion
GET	/user/notification/list	Notifications auflisten
GET	/user/notification/{notificationid}	Notification lesen
DELETE	/user/notification	Notification(s) löschen
PATCH	/user/notification/{notificationid}/status/{status}	Status ändern
GET	/user/notification/settings	Notification Settings
POST	/user/notification/settings/{notification_type}/enable	Typ aktivieren
POST	/user/notification/settings/{notification_type}/disable	Typ deaktivieren

---

14. User Administration / Bans

Method	Endpoint	Funktion
POST	/user/{uid}/accept	Benutzer als Mitglied akzeptieren
DELETE	/user/{uid}	Benutzer löschen
GET	/user/ban/list	Bannliste
GET	/user/ban	Banninformationen
PUT	/user/ban	Bann erstellen
DELETE	/user/ban	Bann entfernen
DELETE	/user/ban/history/{historyid}	Bann-History-Eintrag löschen

Das „Akzeptieren“ eines Users ist unabhängig vom Application-Plugin.

---

15. Member API

Informationen

Method	Endpoint	Funktion
GET	/member/roles	Rollen
GET	/member/ranks	Ranks
GET	/member/perms	Permissions
GET	/member/list	Mitgliederliste
GET	/member/banner	Mitgliederbanner

Eigene Member-Aktionen

Method	Endpoint	Funktion
PATCH	/member/roles/rank	Default Rank-Rolle ändern
PATCH	/member/roles/rank/{rank_type_id}	Rank-Rolle bestimmten Typs ändern
GET	/member/bonus/history	Bonus-History
POST	/member/bonus/claim	Bonus beanspruchen
GET	/member/bonus/notification/settings	Bonus-Notification-Settings
PATCH	/member/bonus/notification/settings	Settings ändern
DELETE	/member/roles/history/{historyid}	Rollen-History löschen
POST	/member/resign	Mitgliedschaft niederlegen

Member Administration

Method	Endpoint	Funktion
PATCH	/member/{userid}/roles	Rollen ändern
PATCH	/member/{userid}/points	Punkte ändern
POST	/member/{userid}/dismiss	Mitglied entlassen

---

16. Driving Logs – /dlog

Method	Endpoint	Funktion
GET	/dlog/list	Fahrten auflisten
GET	/dlog/{logid}	einzelne Fahrt
DELETE	/dlog/{logid}	Fahrt löschen
GET	/dlog/leaderboard	Leaderboard
GET	/dlog/export	Fahrten exportieren
GET	/dlog/statistics/summary	aggregierte Statistik
GET	/dlog/statistics/chart	Chart-Daten
GET	/dlog/statistics/details	Detailstatistik

Diese APIs gehören zu den mächtigeren Teilen des Backends und besitzen zahlreiche Filter für beispielsweise:

Fahrer
Zeiträume
Distanz
Einnahmen
Schaden
Fahrzeug
Fracht
Start-/Zielort
Spiel
Tracker

Die Filter sollten anhand der jeweiligen OpenAPI-Definition verwendet werden, da die Statistik-Endpoints unterschiedlich große Parametersätze besitzen.

---

17. Tracker APIs

Tracker-Routen werden nur aktiviert, wenn der entsprechende Tracker konfiguriert ist.

TrackSim

Method	Endpoint
POST	/tracksim/update
POST	/tracksim/update/route
PUT	/tracksim/driver/{userid}
DELETE	/tracksim/driver/{userid}

Trucky

Method	Endpoint
POST	/trucky/update
POST	/trucky/import/{jobid}
PUT	/trucky/driver/{userid}
DELETE	/trucky/driver/{userid}

Custom Tracker

POST /custom-tracker/update

UniTracker

POST /unitracker/update

Diese Endpoints sind primär für Tracker-Server/Webhooks gedacht, nicht für den normalen Browser-Client.

---

18. Announcements Plugin

Nur vorhanden, wenn das Plugin aktiviert ist.

Method	Endpoint	Funktion
GET	/announcements/types	Announcement-Typen
GET	/announcements/list	Liste
GET	/announcements/{announcementid}	Eintrag
POST	/announcements	erstellen
PATCH	/announcements/{announcementid}	ändern
DELETE	/announcements/{announcementid}	löschen

---

19. Applications Plugin

Method	Endpoint	Funktion
GET	/applications/types	Application-Typen
GET	/applications/list	Bewerbungen
GET	/applications/statistics	Statistiken
GET	/applications/{applicationid}	Bewerbung
POST	/applications	Bewerbung erstellen
POST	/applications/{applicationid}/message	Nachricht hinzufügen
PATCH	/applications/{applicationid}/status	Status ändern
DELETE	/applications/{applicationid}	löschen

Hinweis: Das Akzeptieren einer Application akzeptiert den User nicht automatisch als Hub-Mitglied.

---

20. Challenges Plugin

Method	Endpoint
GET	/challenges/list
GET	/challenges/{challengeid}
POST	/challenges
PATCH	/challenges/{challengeid}
DELETE	/challenges/{challengeid}
PUT	/challenges/{challengeid}/delivery/{logid}
DELETE	/challenges/{challengeid}/delivery/{logid}

Die letzten beiden Calls ordnen Driving Logs einer Challenge zu bzw. entfernen sie.

---

21. Divisions Plugin

Method	Endpoint
GET	/divisions/list
GET	/divisions/statistics
GET	/divisions/{divisionid}/activity
GET	/divisions/list/pending
GET	/dlog/{logid}/division
POST	/dlog/{logid}/division/{divisionid}
PATCH	/dlog/{logid}/division/{divisionid}

---

22. Downloads Plugin

Method	Endpoint
GET	/downloads/list
GET	/downloads/redirect/{secret}
GET	/downloads/{downloadsid}
POST	/downloads
PATCH	/downloads/{downloadsid}
DELETE	/downloads/{downloadsid}

/downloads/redirect/{secret} dient dem kontrollierten Download/Redirect anhand eines Secrets.

---

23. Economy Plugin

Das Economy-Plugin besitzt eine umfangreiche eigene API.

Economy Overview

GET /economy

---

Balance

Method	Endpoint
GET	/economy/balance
GET	/economy/balance/{userid}
PATCH	/economy/balance/{userid}
GET	/economy/balance/leaderboard
POST	/economy/balance/transfer
GET	/economy/balance/{userid}/transactions/list
GET	/economy/balance/{userid}/transactions/export
POST	/economy/balance/{userid}/visibility/{visibility}

---

Garages

Method	Endpoint
GET	/economy/garages
GET	/economy/garages/list
GET	/economy/garages/{garageid}
POST	/economy/garages/{garageid}/purchase
POST	/economy/garages/{garageid}/transfer
POST	/economy/garages/{garageid}/sell

Garage Slots

Method	Endpoint
GET	/economy/garages/{garageid}/slots/list
GET	/economy/garages/{garageid}/slots/{slotid}
POST	/economy/garages/{garageid}/slots/purchase
POST	/economy/garages/{garageid}/slots/{slotid}/transfer
POST	/economy/garages/{garageid}/slots/{slotid}/sell

---

Trucks

Method	Endpoint
GET	/economy/trucks
GET	/economy/trucks/list
GET	/economy/trucks/{vehicleid}
GET	/economy/trucks/{vehicleid}/{operation}/history
POST	/economy/trucks/{truckid}/purchase
POST	/economy/trucks/{vehicleid}/transfer
POST	/economy/trucks/{vehicleid}/relocate
POST	/economy/trucks/{vehicleid}/activate
POST	/economy/trucks/{vehicleid}/deactivate
POST	/economy/trucks/{vehicleid}/repair
POST	/economy/trucks/{vehicleid}/sell
POST	/economy/trucks/{vehicleid}/scrap

---

Merchandise

Method	Endpoint
GET	/economy/merch
GET	/economy/merch/list
POST	/economy/merch/{merchid}/purchase
POST	/economy/merch/{itemid}/transfer
POST	/economy/merch/{itemid}/sell

---

24. Events Plugin

Method	Endpoint
GET	/events/list
GET	/events/{eventid}
PUT	/events/{eventid}/vote
DELETE	/events/{eventid}/vote
POST	/events
PATCH	/events/{eventid}
DELETE	/events/{eventid}
PATCH	/events/{eventid}/attendees

Beim Bearbeiten von Attendees werden User-IDs verwendet.

---

25. Poll Plugin

Method	Endpoint
GET	/polls/list
GET	/polls/{pollid}
PUT	/polls/{pollid}/vote
PATCH	/polls/{pollid}/vote
DELETE	/polls/{pollid}/vote
POST	/polls
PATCH	/polls/{pollid}
DELETE	/polls/{pollid}

GET /polls/list unterstützt u. a.:

page
page_size
order_by
order

order_by kann beispielsweise:

orderid
pollid
title
timestamp
end_time

sein.

---

26. Tasks Plugin

Method	Endpoint
GET	/tasks/list
GET	/tasks/{taskid}
POST	/tasks
PATCH	/tasks/{taskid}
DELETE	/tasks/{taskid}
PUT	/tasks/{taskid}/complete/mark
DELETE	/tasks/{taskid}/complete/mark
POST	/tasks/{taskid}/complete/accept
POST	/tasks/{taskid}/complete/reject

Der typische Workflow ist:

Task erstellen
      ↓
User markiert Task als erledigt
      ↓
Staff akzeptiert oder verwirft die Completion

---

27. Beispiel eines kompletten Clients

Shell-Setup:

BASE="https://hub.example.com/api"
TOKEN="..."

Status

curl -sS "$BASE/status"

Login

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Secret123!",
    "captcha-response": "CAPTCHA_TOKEN"
  }' \
  "$BASE/auth/password"

Response:

{
  "token": "e1234567-89ab-cdef-0123-456789abcdef",
  "mfa": false
}

Eigenes Profil

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile"

Fremdes Profil anhand UID

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile?uid=42"

Profil ändern

curl -sS \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kosmos",
    "avatar": "https://example.com/avatar.png"
  }' \
  "$BASE/user/profile"

Driving Logs

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/dlog/list?page=1&page_size=50"

Token prüfen

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/token"

Logout / Token widerrufen

curl -sS \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE/token"

---

28. Wichtige Besonderheiten für Client-Entwickler

1. Nicht alle Endpoints sind immer vorhanden

Tracker-Endpunkte hängen von den konfigurierten Trackern ab.

Plugin-Endpunkte hängen von den aktivierten Plugins ab.

Ein 404 Not Found kann daher bedeuten, dass die entsprechende Funktion im aktuellen Hub deaktiviert ist.

2. Permissions sind dynamisch

Viele Endpoints verlangen keine fest im Endpointnamen sichtbare Rolle wie admin.

Die Autorisierung basiert auf:

User accepted?
+
Roles
+
Permissions der Rollen

Ein Benutzer muss mindestens eine passende Permission besitzen.

3. Application Token != User Token

Ein Application Token wird vom System ausdrücklich anders behandelt.

Ein Client sollte daher nicht davon ausgehen, dass jeder Bearer-Endpunkt automatisch mit Application Token funktioniert.

4. OpenAPI beschreibt Responses kaum

Viele Definitionen enthalten:

"responses": {}

Für einen streng typisierten Client sollte man Response-Schemas daher aus der Implementierung bzw. aus echten Testantworten ableiten.

5. Captcha-Abweichung

Bei /auth/password, /auth/register und /auth/reset sollte der Client immer:

"captcha-response": "..."

mitsenden.

Zumindest beim Password-Login greift die Implementierung direkt auf dieses Feld zu.

6. API-Versionierung

Die API verwendet keine Versionsnummer im URL-Pfad wie:

/api/v1/...

Die Kompatibilität hängt daher von der eingesetzten HubBackend-Version ab.

---

29. Empfehlung für eine eigene Integration

Für einen normalen Web-/Desktop-Client würde ich folgende Reihenfolge verwenden:

GET /
   ↓
GET /languages
   ↓
POST /auth/password
   ↓
optional POST /auth/mfa
   ↓
GET /token
   ↓
GET /user/profile
   ↓
GET /member/perms
   ↓
Features abhängig von Permissions anzeigen

Danach können beispielsweise:

/dlog/*
/member/*
/announcements/*
/applications/*
/events/*
/economy/*

verwendet werden.

Für einen generischen Client ist es sinnvoll, nicht hart anzunehmen, welche Plugins vorhanden sind, sondern die Hub-Konfiguration bzw. verfügbaren Funktionen beim Start festzustellen.

---

30. Kurzreferenz der API-Bereiche

/                         Server/Hub Info
/status                   Status
/config                   Administration
/audit                    Audit Log

/auth/*                   Login / Registration
/token/*                  Sessions / Application Tokens

/user/*                   Accounts
/member/*                 Mitglieder / Rollen / Punkte
/dlog/*                   Driving Logs & Statistiken

/tracksim/*               TrackSim
/trucky/*                 Trucky
/custom-tracker/*         Custom Tracker
/unitracker/*             UniTracker

/announcements/*          Announcements Plugin
/applications/*           Applications Plugin
/challenges/*             Challenge Plugin
/divisions/*              Division Plugin
/downloads/*              Downloads Plugin
/economy/*                Economy Plugin
/events/*                 Event Plugin
/polls/*                  Poll Plugin
/tasks/*                  Task Plugin