Ü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
Erstellt ein neues Benutzerkonto. Ein Verifizierungslink wird an die angegebene E-Mail-Adresse gesendet.
Request Body:
{
"email" : "[email protected] " ,
"name" : "John Doe" ,
"password" : "SecurePassword123!"
}
Vollständiger Name (mindestens 2 Zeichen)
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
Authentifiziert einen Benutzer und startet eine Sitzung.
Request Body:
E-Mail-Adresse 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
Ruft die Informationen des aktuell authentifizierten Benutzers ab.
Headers:
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
Fordert einen neuen Access-Token mithilfe des Refresh-Tokens an.
Headers:
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
Beendet die Sitzung des Benutzers und invalidiert Tokens.
Headers:
Response:
{
"success" : true ,
"message" : "Logged out successfully"
}
Cookies gelöscht:
accessToken entfernt
refreshToken entfernt
E-Mail verifizieren
Verifiziert die E-Mail-Adresse eines Benutzers mit dem per E-Mail gesendeten Verifizierungstoken.
Request Body:
{
"token" : "verification_token_from_email"
}
E-Mail-Verifizierungstoken
Response:
{
"success" : true ,
"message" : "Email verified successfully. You can now log in."
}
Verifizierungs-E-Mail erneut senden
/auth/send-email-verification
Fordert eine neue Verifizierungs-E-Mail an, falls die vorherige abgelaufen ist oder verloren ging.
Request Body:
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
Fordert einen Link zum Zurücksetzen des Passworts per E-Mail an.
Request Body:
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
Setzt das Passwort mit dem per E-Mail erhaltenen Token zurück.
Request Body:
{
"token" : "reset_token_from_email" ,
"password" : "NewSecurePassword123!"
}
Passwort-Reset-Token aus der E-Mail
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
Code Status Beschreibung INVALID_CREDENTIALS401 E-Mail oder Passwort falsch EMAIL_ALREADY_EXISTS409 E-Mail ist bereits registriert EMAIL_NOT_VERIFIED403 E-Mail-Verifizierung erforderlich INVALID_TOKEN400 Token ist ungültig oder abgelaufen TOKEN_EXPIRED401 Token ist abgelaufen WEAK_PASSWORD400 Passwort erfüllt die Anforderungen nicht RATE_LIMIT_EXCEEDED429 Zu 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
Immer HTTPS in der Produktion verwenden
Übertragen Sie Zugangsdaten niemals über ungesicherte HTTP-Verbindungen.
Clientseitigen Token-Refresh implementieren
Erneuern Sie Tokens automatisch vor Ablauf, um die Sitzung aufrechtzuerhalten.
Refresh-Tokens sicher speichern
Verwenden Sie HTTP-only Cookies (automatisch von unserer API gehandhabt) statt localStorage.
Starke Passwort-Richtlinien durchsetzen
Fordern Sie Passwörter mit ausreichender Komplexität und Länge.
Ratenbegrenzung implementieren
Schützen Sie Authentifizierungs-Endpunkte vor Brute-Force-Angriffen.
Authentifizierungsereignisse protokollieren
Protokollieren Sie Login-Versuche, Passwort-Resets und verdächtige Aktivitäten.
Verwandte Ressourcen