Kundenportal API — Multi-Tenant REST-API für das Kundenportal

Das Kundenportal ist eine Vue 3 SPA, die über diese REST-API Tickets erstellt, Geräte einsieht, Wiki-Artikel liest, Zugangsdaten offenlegt und Rechnungen/Angebote verwaltet.

Inhalt

1. Authentifizierung (2-Stufen)
2. Auth-Endpunkte
3. Tickets
4. Geräte
5. Wiki
6. Zugangsdaten
7. Rechnungen
8. Angebote
9. Weitere Endpunkte
10. Berechtigungen

1. Authentifizierung (2-Stufen)

Die Portal-API nutzt ein zweistufiges Auth-Modell:

Stufe	Header	Beschreibung
1. Instanz	X-Portal-Token: <instance_token>	Identifiziert die Kundeninstanz. Immer erforderlich.
2. Benutzer	Authorization: Bearer <session_token>	Session-Token vom Login. Für die meisten Endpunkte erforderlich.

Basis-URL: /api/portal

Hinweis: Endpunkte wie Login, Branding und Attachment-Downloads benötigen nur das Instanz-Token. Alle anderen erfordern zusätzlich den Bearer-Token.

POST /auth/login

Benutzer anmelden. Rate-Limit: 5 Versuche pro IP / 15 Minuten.

Feld	Typ	Beschreibung
email	email	E-Mail-Adresse
password	string	Passwort

{
  "session_token": "uuid-session-id",
  "expires_at": "2026-03-04T10:00:00+00:00",
  "user": { "id": 1, "name": "Max", "email": "max@firma.de", "role": "admin", "permissions": {} },
  "customer": { "id": 1, "name": "Firma GmbH", "short_name": "Firma" }
}

POST /auth/forgot-password

Passwort-Reset anfordern. Gibt immer die gleiche Antwort zurück (verhindert User-Enumeration). Rate-Limit: 3/15 Min.

POST /auth/reset-password

Passwort zurücksetzen mit Token. Felder: email, token, password, password_confirmation. Token 60 Min. gültig.

POST /auth/logout · GET /auth/me · PUT /auth/password

Session beenden, Benutzerdaten abrufen, Passwort ändern (erfordert current_password + new_password).

3. Tickets (Berechtigung: `tickets`)

Methode	Endpunkt	Beschreibung
GET	/tickets	Liste (Filter: state_id, category_id, search, per_page)
GET	/tickets/kanban	Kanban-Board (offene Tickets gruppiert nach Status)
POST	/tickets	Neues Ticket (title, body, attachments max 5×10MB)
GET	/tickets/{'{id}'}	Detail + Artikel (ohne interne Notizen)
POST	/tickets/{'{id}'}/reply	Antwort + Anhänge
POST	/tickets/{'{id}'}/close	Ticket schließen
GET	/tickets/categories	Verfügbare Kategorien
GET	/tickets/states	Alle Ticket-Status
POST	/tickets/upload-image	Inline-Bild für Tiptap-Editor (max 5MB)

Ticket erstellen — Beispiel

curl -X POST https://it-dashboard.de/api/portal/tickets \
  -H "X-Portal-Token: instance-token" \
  -H "Authorization: Bearer session-token" \
  -F "title=Drucker funktioniert nicht" \
  -F "body=Der Drucker im 2. OG druckt nicht mehr." \
  -F "category_id=3" \
  -F "attachments[0]=@screenshot.png"

Erlaubte Dateitypen: jpg, png, gif, webp, pdf, doc, docx, xls, xlsx, zip, rar, txt, csv. Max 5 Dateien à 10 MB.

Interne Notizen werden automatisch gefiltert — Kunden sehen nur externe Artikel (internal = false).

4. Geräte (Berechtigung: `devices`)

Methode	Endpunkt	Berechtigung	Beschreibung
GET	/devices	devices	Geräteliste (Name, Typ, Status, Online — keine IPs/MACs/Credentials)
GET	/devices/stats	devices	Statistiken (total, online, offline)
POST	/devices/{'{id}'}/remote-session	remote	MeshCentral Remote-Desktop-Link erstellen
POST	/devices/{'{id}'}/restart	remote	Gerät neustarten (Wake-on-LAN)

Sicherheit: Die Geräteliste gibt bewusst keine IP-Adressen, MAC-Adressen, SNMP-Credentials oder interne Netzwerkdaten zurück.

5. Wiki (Berechtigung: `wiki`)

Methode	Endpunkt	Beschreibung
GET	/wiki	Liste aller Portal-sichtbaren Wiki-Artikel
GET	/wiki/search?q=vpn	Suche (min. 2 Zeichen)
GET	/wiki/{'{id}'}	Artikel anzeigen (zählt Views)

6. Zugangsdaten (Berechtigung: `credentials`)

Methode	Endpunkt	Beschreibung
GET	/credentials	Liste (ohne Passwörter! Nur Metadaten + has_password)
POST	/credentials/{'{id}'}/reveal	Passwort + OTP anzeigen (wird auditiert)

Sichtbare Felder werden pro Credential über portal_visible_fields konfiguriert. Zeitlich begrenzte Zugänge (time_limited) haben ein Ablaufdatum.

7. Rechnungen (Berechtigung: `billing`)

Methode	Endpunkt	Beschreibung
GET	/invoices	Liste + Statistiken (Filter: status, search, per_page)
GET	/invoices/{'{id}'}	Detail mit Positionen, Zahlungen, Steuer-Aufschlüsselung
GET	/invoices/{'{id}'}/pdf	PDF-Download

Entwurf-Rechnungen (status: draft) werden nicht angezeigt. Statistiken enthalten: offene/bezahlte/überfällige Anzahl und offener Gesamtbetrag.

8. Angebote (Berechtigung: `billing`)

Methode	Endpunkt	Beschreibung
GET	/quotes	Liste + Statistiken
GET	/quotes/{'{id}'}	Detail mit Positionen + can_respond Flag
GET	/quotes/{'{id}'}/pdf	PDF-Download
POST	/quotes/{'{id}'}/accept	Angebot annehmen (nur wenn status=sent, nicht abgelaufen)
POST	/quotes/{'{id}'}/reject	Angebot ablehnen

9. Weitere Endpunkte

Methode	Endpunkt	Auth	Beschreibung
GET	/branding/{'{customerId?}'}	Instanz	Portal-Branding (Name, Logo, Farben, Support-Kontakt)
GET	/download-package	Instanz	Portal Vue-SPA als ZIP
GET	/ticket-attachments/{'{id}'}/download	Instanz	Anhang herunterladen (kein Bearer nötig für img-Tags)
GET	/documents	Benutzer	Portal-sichtbare Dokumente (Berechtigung: documents)
GET	/company	Benutzer	Firmen-Informationen
GET	/contacts	Benutzer	Ansprechpartner des Kunden

10. Berechtigungen

Portal-Benutzer haben eine Rolle und individuelle Modul-Berechtigungen:

Rollen

Rolle	Beschreibung
admin	Vollzugriff auf alle freigegebenen Module
user	Standard-Benutzer (lesen + schreiben)
readonly	Nur-Lese-Zugriff (keine Ticket-Erstellung, keine Aktionen)

Modul-Berechtigungen

Modul	Freigegebene Funktionen
tickets	Tickets erstellen, anzeigen, antworten, schließen
devices	Geräteliste und Statistiken anzeigen
remote	Remote-Desktop und Neustart
wiki	Wiki-Artikel lesen und suchen
credentials	Freigegebene Zugangsdaten anzeigen/offenlegen
documents	Dokumente anzeigen
billing	Rechnungen, Angebote, PDFs