> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentifizierungs-API

> Benutzerauthentifizierung, Registrierung und Sitzungsverwaltung

## Ü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

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client
    participant API
    participant Email

    User->>Client: Enter credentials
    Client->>API: POST /auth/register
    API->>Email: Send verification email
    API-->>Client: Success (unverified account)
    User->>Email: Click verification link
    Email->>API: POST /auth/verify-email
    API-->>Client: Email verified
    User->>Client: Login
    Client->>API: POST /auth/login
    API-->>Client: Set HTTP-only cookie
    Client->>API: Authenticated requests
```

## Endpunkte

### Neuen Benutzer registrieren

<ParamField path="POST" type="endpoint">
  /auth/register
</ParamField>

Erstellt ein neues Benutzerkonto. Ein Verifizierungslink wird an die angegebene E-Mail-Adresse gesendet.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com",
  "name": "John Doe",
  "password": "SecurePassword123!"
}
```

<ParamField body="email" type="string" required>
  Gültige E-Mail-Adresse
</ParamField>

<ParamField body="name" type="string" required>
  Vollständiger Name (mindestens 2 Zeichen)
</ParamField>

<ParamField body="password" type="string" required>
  Starkes Passwort (mindestens 8 Zeichen)
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Registration successful. Please check your email to verify your account.",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "emailVerified": false,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}
```

<Warning>
  Benutzer müssen ihre E-Mail-Adresse verifizieren, bevor sie vollen Zugriff auf die Plattform erhalten.
</Warning>

***

### Login

<ParamField path="POST" type="endpoint">
  /auth/login
</ParamField>

Authentifiziert einen Benutzer und startet eine Sitzung.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}
```

<ParamField body="email" type="string" required>
  E-Mail-Adresse des Benutzers
</ParamField>

<ParamField body="password" type="string" required>
  Passwort des Benutzers
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "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

<ParamField path="GET" type="endpoint">
  /auth/me
</ParamField>

Ruft die Informationen des aktuell authentifizierten Benutzers ab.

**Headers:**

```
Cookie: accessToken=...
```

**Response:**

```json theme={null}
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}
```

***

### Access-Token erneuern

<ParamField path="POST" type="endpoint">
  /auth/refresh
</ParamField>

Fordert einen neuen Access-Token mithilfe des Refresh-Tokens an.

**Headers:**

```
Cookie: refreshToken=...
```

**Response:**

```json theme={null}
{
  "ok": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER"
  }
}
```

**Cookies aktualisiert:**

* Neuer `accessToken` wird ausgegeben
* `refreshToken` wird aus Sicherheitsgründen rotiert

***

### Logout

<ParamField path="POST" type="endpoint">
  /auth/logout
</ParamField>

Beendet die Sitzung des Benutzers und invalidiert Tokens.

**Headers:**

```
Cookie: accessToken=...
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Logged out successfully"
}
```

**Cookies gelöscht:**

* `accessToken` entfernt
* `refreshToken` entfernt

***

### E-Mail verifizieren

<ParamField path="POST" type="endpoint">
  /auth/verify-email
</ParamField>

Verifiziert die E-Mail-Adresse eines Benutzers mit dem per E-Mail gesendeten Verifizierungstoken.

**Request Body:**

```json theme={null}
{
  "token": "verification_token_from_email"
}
```

<ParamField body="token" type="string" required>
  E-Mail-Verifizierungstoken
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Email verified successfully. You can now log in."
}
```

***

### Verifizierungs-E-Mail erneut senden

<ParamField path="POST" type="endpoint">
  /auth/send-email-verification
</ParamField>

Fordert eine neue Verifizierungs-E-Mail an, falls die vorherige abgelaufen ist oder verloren ging.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com"
}
```

<ParamField body="email" type="string" required>
  E-Mail-Adresse des Benutzers
</ParamField>

**Response:**

```json theme={null}
{
  "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

<ParamField path="POST" type="endpoint">
  /auth/forgot-password
</ParamField>

Fordert einen Link zum Zurücksetzen des Passworts per E-Mail an.

**Request Body:**

```json theme={null}
{
  "email": "user@example.com"
}
```

<ParamField body="email" type="string" required>
  E-Mail-Adresse des Benutzers
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent."
}
```

<Info>
  Aus Sicherheitsgründen gibt die API immer eine Erfolgsmeldung zurück, unabhängig davon, ob die E-Mail existiert.
</Info>

***

### Passwort zurücksetzen

<ParamField path="POST" type="endpoint">
  /auth/reset-password
</ParamField>

Setzt das Passwort mit dem per E-Mail erhaltenen Token zurück.

**Request Body:**

```json theme={null}
{
  "token": "reset_token_from_email",
  "password": "NewSecurePassword123!"
}
```

<ParamField body="token" type="string" required>
  Passwort-Reset-Token aus der E-Mail
</ParamField>

<ParamField body="password" type="string" required>
  Neues Passwort (mindestens 8 Zeichen)
</ParamField>

**Response:**

```json theme={null}
{
  "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_CREDENTIALS`  | 401    | E-Mail oder Passwort falsch              |
| `EMAIL_ALREADY_EXISTS` | 409    | E-Mail ist bereits registriert           |
| `EMAIL_NOT_VERIFIED`   | 403    | E-Mail-Verifizierung erforderlich        |
| `INVALID_TOKEN`        | 400    | Token ist ungültig oder abgelaufen       |
| `TOKEN_EXPIRED`        | 401    | Token ist abgelaufen                     |
| `WEAK_PASSWORD`        | 400    | Passwort erfüllt die Anforderungen nicht |
| `RATE_LIMIT_EXCEEDED`  | 429    | Zu viele Anfragen                        |

## Anwendungsfälle

### Beispiel 1: Vollständiger Registrierungsablauf

```bash theme={null}
# Step 1: Register
curl -X POST "https://api.steerai.autos/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com",
    "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": "dealer@example.com",
    "password": "SecurePass123!"
  }'
```

### Beispiel 2: Passwort-Reset-Ablauf

```bash theme={null}
# Step 1: Request reset
curl -X POST "https://api.steerai.autos/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com"
  }'

# 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

```bash theme={null}
# 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

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="Immer HTTPS in der Produktion verwenden">
    Übertragen Sie Zugangsdaten niemals über ungesicherte HTTP-Verbindungen.
  </Accordion>

  <Accordion title="Clientseitigen Token-Refresh implementieren">
    Erneuern Sie Tokens automatisch vor Ablauf, um die Sitzung aufrechtzuerhalten.
  </Accordion>

  <Accordion title="Refresh-Tokens sicher speichern">
    Verwenden Sie HTTP-only Cookies (automatisch von unserer API gehandhabt) statt localStorage.
  </Accordion>

  <Accordion title="Starke Passwort-Richtlinien durchsetzen">
    Fordern Sie Passwörter mit ausreichender Komplexität und Länge.
  </Accordion>

  <Accordion title="Ratenbegrenzung implementieren">
    Schützen Sie Authentifizierungs-Endpunkte vor Brute-Force-Angriffen.
  </Accordion>

  <Accordion title="Authentifizierungsereignisse protokollieren">
    Protokollieren Sie Login-Versuche, Passwort-Resets und verdächtige Aktivitäten.
  </Accordion>
</AccordionGroup>

## Verwandte Ressourcen

<CardGroup cols={2}>
  <Card title="Erste Schritte" icon="rocket" href="/de/getting-started/authentication">
    Schnellstart-Anleitung zur Authentifizierung
  </Card>

  <Card title="Sicherheitsleitfaden" icon="shield" href="/de/guides/security">
    Umfassende bewährte Sicherheitspraktiken
  </Card>

  <Card title="Benutzer-API" icon="user" href="/de/api-reference/users/management">
    Benutzerverwaltung und Profil-Endpunkte
  </Card>

  <Card title="Teams-API" icon="users" href="/de/api-reference/teams/overview">
    Team-Zusammenarbeit und Berechtigungen
  </Card>
</CardGroup>