Authentifizierung

Alle API-Anfragen werden per JWT-Token authentifiziert. Es gibt zwei separate Authentifizierungssysteme: eines für Admin-Benutzer und eines für Kunden (Endkäufer).

Admin-Authentifizierung

Admin-Routen unter /api2/admin/* sind durch JWT-Cookies geschützt.

Anmeldung

POST /api2/admin/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "IhrPasswort"
}

Bei erfolgreicher Anmeldung werden zwei HttpOnly-Cookies gesetzt:

Cookie	Gültigkeit	Beschreibung
`admin_auth_token`	4 Stunden	Zugriffs-Token für API-Anfragen
`admin_refresh_token`	7 Tage	Token zur automatischen Token-Erneuerung

Token-Erneuerung

POST /api2/admin/refresh

Erneuert den admin_auth_token automatisch, solange der admin_refresh_token gültig ist. Wird vom Frontend automatisch aufgerufen.

Ausloggen

POST /api2/admin/logout

Löscht beide Auth-Cookies serverseitig.

Berechtigungen (RBAC)

Das System verwendet rollenbasierte Zugriffskontrolle mit 6 Rollen:

Rolle	Beschreibung
`super_admin`	Vollzugriff auf alle Funktionen
`admin`	Vollzugriff auf Shop-Verwaltung
`manager`	Bestellungen, Produkte, Kunden
`editor`	Produkte und Inhalte bearbeiten
`support`	Nur-Lese-Zugriff auf Bestellungen und Kunden
`viewer`	Nur-Lese-Zugriff auf alle Bereiche

CSRF-Schutz

Mutationen (POST, PUT, PATCH, DELETE) erfordern einen CSRF-Token. Dieser wird als X-CSRF-Token-Header mitgesendet:

POST /api2/admin/products
X-CSRF-Token: <csrf-token>
Content-Type: application/json

Den CSRF-Token erhalten Sie aus dem /api2/admin/me-Endpunkt. GET-Anfragen benötigen keinen CSRF-Token.

Kunden-Authentifizierung

Für Endkunden (Käufer) gibt es ein separates Auth-System unter /api2/auth/.

Registrierung

POST /api2/auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SicheresPasswort1",
  "firstName": "Max",
  "lastName": "Mustermann"
}

Antwort (201):

{
  "needsVerification": true,
  "message": "Bitte bestätigen Sie Ihre E-Mail-Adresse."
}

Passwortanforderungen: 8–128 Zeichen, mind. 1 Großbuchstabe, 1 Kleinbuchstabe, 1 Ziffer.

E-Mail-Verifizierung

GET /api2/auth/verify?token=<verification-token>

Antwort	Bedeutung
`200 { verified: true }`	Erfolgreich verifiziert
`200 { alreadyVerified: true }`	Bereits verifiziert (idempotent)
`400`	Ungültiger oder abgelaufener Token

Anmeldung

POST /api2/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SicheresPasswort1"
}

Bei Erfolg wird ein auth_token-Cookie gesetzt (HttpOnly, 24 Stunden). Nicht-verifizierte Konten erhalten 403 mit { needsVerification: true }.

Aktuelle Session abrufen

GET /api2/auth/me

Gibt die Daten des aktuell eingeloggten Kunden zurück (aus dem auth_token-Cookie).

Ausloggen

POST /api2/auth/logout

Löscht das auth_token-Cookie.

Fehlerantworten

Alle API-Endpunkte geben standardisierte Fehlerantworten zurück:

{
  "error": "Fehlermeldung",
  "code": "ERROR_CODE"
}

HTTP-Status	Bedeutung
`400`	Ungültige Anfrage / Validierungsfehler
`401`	Nicht authentifiziert
`403`	Keine Berechtigung für diese Aktion
`404`	Ressource nicht gefunden
`429`	Zu viele Anfragen (Rate Limit erreicht)
`500`	Interner Serverfehler

Rate Limiting

Auth-Endpunkte sind zusätzlich rate-limitiert, um Brute-Force-Angriffe zu verhindern. Nach mehreren fehlgeschlagenen Versuchen werden weitere Anfragen temporär blockiert.

Siehe Rate Limiting für Details.