Zum Hauptinhalt springen

Überblick

Die Authentifizierungs-API verwaltet Benutzerregistrierung, Login, Sitzungsverwaltung, E-Mail-Verifizierung und Passwort-Reset-Flows. Die Authentifizierung nutzt sichere HTTP-only Cookies für die Sitzungsverwaltung mit JWT-Tokens.

Authentifizierungsablauf

Endpunkte

Neuen Benutzer registrieren

POST
endpoint
/auth/register
Erstellt ein neues Benutzerkonto. Ein Verifizierungslink wird an die angegebene E-Mail-Adresse gesendet. Request Body:
{
  "email": "[email protected]",
  "name": "John Doe",
  "password": "SecurePassword123!"
}
email
string
erforderlich
Gültige E-Mail-Adresse
name
string
erforderlich
Vollständiger Name (mindestens 2 Zeichen)
password
string
erforderlich
Starkes Passwort (mindestens 8 Zeichen)
Response:
{
  "success": true,
  "message": "Registration successful. Please check your email to verify your account.",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe",
    "emailVerified": false,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}
Benutzer müssen ihre E-Mail-Adresse verifizieren, bevor sie vollen Zugriff auf die Plattform erhalten.

Login

POST
endpoint
/auth/login
Authentifiziert einen Benutzer und startet eine Sitzung. Request Body:
{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}
email
string
erforderlich
E-Mail-Adresse des Benutzers
password
string
erforderlich
Passwort des Benutzers
Response:
{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true
  }
}
Cookies gesetzt:
  • accessToken - HTTP-only, Secure, SameSite=Strict (15 Minuten)
  • refreshToken - HTTP-only, Secure, SameSite=Strict (7 Tage)

Aktuellen Benutzer abrufen

GET
endpoint
/auth/me
Ruft die Informationen des aktuell authentifizierten Benutzers ab. Headers:
Cookie: accessToken=...
Response:
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}

Access-Token erneuern

POST
endpoint
/auth/refresh
Fordert einen neuen Access-Token mithilfe des Refresh-Tokens an. Headers:
Cookie: refreshToken=...
Response:
{
  "ok": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "USER"
  }
}
Cookies aktualisiert:
  • Neuer accessToken wird ausgegeben
  • refreshToken wird aus Sicherheitsgründen rotiert

Logout

POST
endpoint
/auth/logout
Beendet die Sitzung des Benutzers und invalidiert Tokens. Headers:
Cookie: accessToken=...
Response:
{
  "success": true,
  "message": "Logged out successfully"
}
Cookies gelöscht:
  • accessToken entfernt
  • refreshToken entfernt

E-Mail verifizieren

POST
endpoint
/auth/verify-email
Verifiziert die E-Mail-Adresse eines Benutzers mit dem per E-Mail gesendeten Verifizierungstoken. Request Body:
{
  "token": "verification_token_from_email"
}
token
string
erforderlich
E-Mail-Verifizierungstoken
Response:
{
  "success": true,
  "message": "Email verified successfully. You can now log in."
}

Verifizierungs-E-Mail erneut senden

POST
endpoint
/auth/send-email-verification
Fordert eine neue Verifizierungs-E-Mail an, falls die vorherige abgelaufen ist oder verloren ging. Request Body:
{
  "email": "[email protected]"
}
email
string
erforderlich
E-Mail-Adresse des Benutzers
Response:
{
  "success": true,
  "message": "Verification email sent. Please check your inbox."
}
Ratenlimit: Dieser Endpunkt ist rate-limitiert, um Missbrauch zu verhindern:
  • 5 Anfragen pro Stunde pro E-Mail-Adresse

Passwort vergessen

POST
endpoint
/auth/forgot-password
Fordert einen Link zum Zurücksetzen des Passworts per E-Mail an. Request Body:
{
  "email": "[email protected]"
}
email
string
erforderlich
E-Mail-Adresse des Benutzers
Response:
{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent."
}
Aus Sicherheitsgründen gibt die API immer eine Erfolgsmeldung zurück, unabhängig davon, ob die E-Mail existiert.

Passwort zurücksetzen

POST
endpoint
/auth/reset-password
Setzt das Passwort mit dem per E-Mail erhaltenen Token zurück. Request Body:
{
  "token": "reset_token_from_email",
  "password": "NewSecurePassword123!"
}
token
string
erforderlich
Passwort-Reset-Token aus der E-Mail
password
string
erforderlich
Neues Passwort (mindestens 8 Zeichen)
Response:
{
  "success": true,
  "message": "Password reset successful. You can now log in with your new password."
}

Sicherheitsfunktionen

HTTP-only Cookies

Alle Sitzungstokens werden in HTTP-only Cookies gespeichert, um XSS-Angriffe zu verhindern. JavaScript kann diese Cookies nicht lesen.

Secure-Flag

Cookies werden als Secure markiert und nur über HTTPS in der Produktion übertragen.

SameSite-Richtlinie

Cookies verwenden SameSite=Strict, um CSRF-Angriffe zu verhindern.

Token-Rotation

Refresh-Tokens werden bei jeder Verwendung rotiert, um Risiken bei kompromittierten Tokens zu minimieren.

Passwortanforderungen

  • Mindestens 8 Zeichen
  • Empfohlen: Mischung aus Groß-/Kleinbuchstaben, Zahlen und Sonderzeichen

Token-Ablauf

  • Access-Token: 15 Minuten
  • Refresh-Token: 7 Tage
  • Verifizierungstoken: 24 Stunden
  • Reset-Token: 1 Stunde

Fehlercodes

CodeStatusBeschreibung
INVALID_CREDENTIALS401E-Mail oder Passwort falsch
EMAIL_ALREADY_EXISTS409E-Mail ist bereits registriert
EMAIL_NOT_VERIFIED403E-Mail-Verifizierung erforderlich
INVALID_TOKEN400Token ist ungültig oder abgelaufen
TOKEN_EXPIRED401Token ist abgelaufen
WEAK_PASSWORD400Passwort erfüllt die Anforderungen nicht
RATE_LIMIT_EXCEEDED429Zu viele Anfragen

Anwendungsfälle

Beispiel 1: Vollständiger Registrierungsablauf

# Step 1: Register
curl -X POST "https://api.steerai.autos/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Auto Dealer",
    "password": "SecurePass123!"
  }'

# Step 2: User receives email and verifies
curl -X POST "https://api.steerai.autos/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "verification_token_from_email"
  }'

# Step 3: Login
curl -X POST "https://api.steerai.autos/v1/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

Beispiel 2: Passwort-Reset-Ablauf

# Step 1: Request reset
curl -X POST "https://api.steerai.autos/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

# Step 2: Reset with token from email
curl -X POST "https://api.steerai.autos/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "password": "NewSecurePass123!"
  }'

Beispiel 3: Token-Refresh

# Refresh access token before it expires
curl -X POST "https://api.steerai.autos/v1/auth/refresh" \
  -b cookies.txt \
  -c cookies.txt

Client-Implementierung

JavaScript/Node.js

class AuthClient {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  async register(email, name, password) {
    const response = await fetch(`${this.baseURL}/auth/register`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, name, password })
    });
    return response.json();
  }

  async login(email, password) {
    const response = await fetch(`${this.baseURL}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include', // Important for cookies
      body: JSON.stringify({ email, password })
    });
    return response.json();
  }

  async getCurrentUser() {
    const response = await fetch(`${this.baseURL}/auth/me`, {
      credentials: 'include'
    });
    return response.json();
  }

  async logout() {
    const response = await fetch(`${this.baseURL}/auth/logout`, {
      method: 'POST',
      credentials: 'include'
    });
    return response.json();
  }
}

Bewährte Praktiken

Übertragen Sie Zugangsdaten niemals über ungesicherte HTTP-Verbindungen.
Erneuern Sie Tokens automatisch vor Ablauf, um die Sitzung aufrechtzuerhalten.
Verwenden Sie HTTP-only Cookies (automatisch von unserer API gehandhabt) statt localStorage.
Fordern Sie Passwörter mit ausreichender Komplexität und Länge.
Schützen Sie Authentifizierungs-Endpunkte vor Brute-Force-Angriffen.
Protokollieren Sie Login-Versuche, Passwort-Resets und verdächtige Aktivitäten.

Verwandte Ressourcen