Suche aufrufen
Menü aufrufen
Kosmos MediaWiki
Toggle preferences menu
Persönliches Menü aufrufen
Nicht angemeldet
Ihre IP-Adresse wird öffentlich sichtbar sein, wenn Sie Änderungen vornehmen.

DriversHub

Aus Kosmos MediaWiki
Weitere Optionen
Version vom 18. August 2026, 21:52 Uhr von Kosmos (Diskussion | Beiträge) (Die Seite wurde neu angelegt: „# Drivers Hub Backend – 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: ```json { "domain": "hub.example.com", "prefix": "/api" } ``` Damit lautet die Base URL: ```text https://hub.example.com/api ``` Ein Request auf: ```text GET /user/profile ``` wird also…“)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)
  1. Drivers Hub Backend – API-Dokumentation

Repository: `CharlesWithC/HubBackend`

    1. 1. API-Grundlagen
      1. Base URL

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

Beispielkonfiguration:

```json { 

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

} ```

Damit lautet die Base URL:

```text https://hub.example.com/api ```

Ein Request auf:

```text GET /user/profile ```

wird also beispielsweise:

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

Der Prefix ist konfigurierbar und muss mit `/` beginnen.

      1. Swagger / OpenAPI

Wenn in der Konfiguration

```json { 

 "openapi": true

} ```

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

```text {prefix}/doc ```

bereit.

Bei `prefix: "/api"` also:

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

Im Repository liegt außerdem:

```text /openapi.json ```

---

  1. 2. Authentifizierung

Es gibt zwei Token-Typen:

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

    1. Bearer Token

Header:

```http Authorization: Bearer <TOKEN> ```

Beispiel:

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

    1. Application Token

Header:

```http Authorization: Application <TOKEN> ```

Beispiel:

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

---

  1. 3. Allgemeine Request-Regeln

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

```http Content-Type: application/json ```

Ausnahmen sind insbesondere Tracker-Webhooks:

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

Diese dürfen tracker-spezifische Payloads verwenden.

Standard-JSON-Request:

```bash curl -X PATCH \ 

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

```

    1. Fehlerformat

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

```json { 

 "error": "Fehlermeldung"

} ```

Typische Statuscodes sind:

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

```json { 

 "error": "Unprocessable Entity"

} ```

ersetzt.

---

  1. 4. Rate Limits

Es gibt globale und endpoint-spezifische Rate Limits.

Global:

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

```text 3 Requests / 60 Sekunden ```

---

  1. 5. Benutzer-IDs: `uid` vs. `userid`

Das ist für Clients besonders wichtig.

      1. `uid`

Interne, eindeutige User-ID.

Jeder Account besitzt eine `uid`.

      1. `userid`

Mitglieds-/Driver-Hub-ID.

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

Daher können APIs je nach Einsatzzweck entweder:

```text uid ```

oder

```text userid ```

verlangen.

---

  1. 6. Login und Authentifizierungsflow
    1. POST `/auth/password`

Login mit E-Mail und Passwort.

      1. Body

```json { 

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

```text Cloudflare Turnstile hCaptcha ```

      1. Erfolgreicher Login ohne MFA

```json { 

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

} ```

      1. Login mit aktiviertem MFA

```json { 

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

} ```

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

Danach:

```http POST /auth/mfa ```

Body:

```json { 

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

} ```

Danach erhält man den eigentlichen Session-Token.

---

    1. POST `/auth/register`

Registriert einen Account per E-Mail/Passwort.

Body:

```json { 

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

```json { 

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

} ```

---

    1. POST `/auth/reset`

Startet einen Password-Reset.

```json { 

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

} ```

---

    1. POST `/auth/email`

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

Query:

```text ?secret=<SECRET> ```

Bei Password-Reset ggf. Body:

```json { 

 "password": "NewSecret123!"

} ```

---

    1. Discord / Steam Login
      1. GET `/auth/discord/callback`

Queryparameter:

```text code error_description callback_url ```

`callback_url` ist erforderlich.

      1. GET `/auth/steam/callback`

Steam-OpenID-Callback.

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

---

  1. 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:

```bash curl \ 

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

```

Tokenliste unterstützt unter anderem:

```text page page_size order_by order ```

Mögliche `order_by`-Werte laut OpenAPI:

```text ip timestamp country_code user_agent last_used_timestamp ```

---

  1. 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.

---

  1. 9. User API
    1. 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 |

      1. GET `/user/profile`

Kann einen Benutzer anhand verschiedener IDs suchen:

```text userid uid discordid steamid truckersmpid email ```

Zusätzliche Parameter:

```text role_history_limit ban_history_limit ```

Ohne Ziel-ID wird typischerweise das eigene Profil verwendet.

Beispiel:

```bash curl \ 

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

```

Oder:

```bash curl \ 

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

```

      1. PATCH `/user/profile`

Body:

```json { 

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

} ```

Optionale Queryparameter:

```text uid sync_from_discord sync_from_steam sync_from_truckersmp ```

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

---

  1. 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 |

---

  1. 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.

---

  1. 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.

---

  1. 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 |

---

  1. 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.

---

  1. 15. Member API
    1. Informationen

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

    1. 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 |

    1. Member Administration

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

---

  1. 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:

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

---

  1. 17. Tracker APIs

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

    1. TrackSim

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

    1. Trucky

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

    1. Custom Tracker

```text POST /custom-tracker/update ```

    1. UniTracker

```text POST /unitracker/update ```

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

---

  1. 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 |

---

  1. 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.

---

  1. 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.

---

  1. 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}` |

---

  1. 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.

---

  1. 23. Economy Plugin

Das Economy-Plugin besitzt eine umfangreiche eigene API.

    1. Economy Overview

```text GET /economy ```

---

    1. 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}` |

---

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

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

---

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

---

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

---

  1. 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.

---

  1. 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.:

```text page page_size order_by order ```

`order_by` kann beispielsweise:

```text orderid pollid title timestamp end_time ```

sein.

---

  1. 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:

```text Task erstellen 

     ↓

User markiert Task als erledigt 

     ↓

Staff akzeptiert oder verwirft die Completion ```

---

  1. 27. Beispiel eines kompletten Clients

Shell-Setup:

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

    1. Status

```bash curl -sS "$BASE/status" ```

    1. Login

```bash curl -sS \ 

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

```

Response:

```json { 

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

} ```

    1. Eigenes Profil

```bash curl -sS \ 

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

```

    1. Fremdes Profil anhand UID

```bash curl -sS \ 

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

```

    1. Profil ändern

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

```

    1. Driving Logs

```bash curl -sS \ 

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

```

    1. Token prüfen

```bash curl -sS \ 

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

```

    1. Logout / Token widerrufen

```bash curl -sS \ 

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

```

---

  1. 28. Wichtige Besonderheiten für Client-Entwickler
      1. 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.

      1. 2. Permissions sind dynamisch

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

Die Autorisierung basiert auf:

```text User accepted? + Roles + Permissions der Rollen ```

Ein Benutzer muss mindestens eine passende Permission besitzen.

      1. 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.

      1. 4. OpenAPI beschreibt Responses kaum

Viele Definitionen enthalten:

```json "responses": {} ```

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

      1. 5. Captcha-Abweichung

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

```json "captcha-response": "..." ```

mitsenden.

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

      1. 6. API-Versionierung

Die API verwendet keine Versionsnummer im URL-Pfad wie:

```text /api/v1/... ```

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

---

  1. 29. Empfehlung für eine eigene Integration

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

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

```text /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.

---

  1. 30. Kurzreferenz der API-Bereiche

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

Abgerufen von „https://wiki.kosmos.ac/index.php?title=DriversHub&oldid=2“