Zwei-Faktor-Authentifizierung

Fügen Sie Ihrem MailLand-Konto eine zusätzliche Sicherheitsebene mit TOTP-basierter Zwei-Faktor-Authentifizierung hinzu. Wenn aktiviert, erfordert die Anmeldung sowohl Ihr Passwort als auch einen zeitbasierten Code aus einer Authenticator-App.

2FA einrichtenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/auth/2fa/setup

curl -X POST https://api.mail.land/v1/auth/2fa/setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "secret": "JBSWY3DPEHPK3PXP",
  "secretMasked": "JBSW...3PXP",
  "otpAuthUri": "otpauth://totp/MailLand:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=MailLand",
  "qrCodeDataUri": "data:image/png;base64,iVBORw0KGgo...",
  "backupCodes": [
    "A1B2C3D4",
    "E5F6G7H8",
    "I9J0K1L2",
    "M3N4O5P6",
    "Q7R8S9T0",
    "U1V2W3X4",
    "Y5Z6A7B8",
    "C9D0E1F2",
    "G3H4I5J6",
    "K7L8M9N0"
  ]
}

POST https://api.mail.land/v1/auth/2fa/enable

{
  "code": "123456"
}

curl -X POST https://api.mail.land/v1/auth/2fa/enable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

{
  "message": "Two-factor authentication enabled successfully"
}

Code verifizierenLink zum Abschnitt kopieren

Wenn die Anmeldung requiresTwoFactor: true zurückgibt, schließen Sie die Authentifizierung durch Verifizierung eines TOTP-Codes ab:

POST https://api.mail.land/v1/auth/2fa/verify

{
  "challengeId": "2fa_challenge_abc123",
  "code": "123456",
  "trustDevice": true
}

trustDevice ist optional. Bei true wird das Gerät 30 Tage lang gemerkt, und 2FA wird bei nachfolgenden Anmeldungen von diesem Gerät übersprungen.

curl -X POST https://api.mail.land/v1/auth/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "2fa_challenge_abc123",
    "code": "123456"
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_a1b2c3d4e5...",
  "deviceTrusted": false
}

Es gibt kein expiresIn und kein user-Objekt in dieser Antwort. deviceTrusted ist true, wenn trustDevice true war. Das Geräte-Token selbst steht nie im Body: Die API setzt es als HttpOnly-Cookie __Host-trusted_device, und der Browser sendet es bei der nächsten Anmeldung mit.

Backup-Code verwendenLink zum Abschnitt kopieren

Falls Sie den Zugriff auf Ihre Authenticator-App verlieren, verwenden Sie stattdessen einen Backup-Code:

POST https://api.mail.land/v1/auth/2fa/verify-backup

{
  "challengeId": "2fa_challenge_abc123",
  "code": "a1b2c3d4"
}

Das Feld heißt code (8–10 Zeichen), nicht backupCode.

curl -X POST https://api.mail.land/v1/auth/2fa/verify-backup \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "2fa_challenge_abc123",
    "code": "a1b2c3d4"
  }'

Gibt dieselbe Antwort wie die TOTP-Verifizierung zurück. Jeder Backup-Code kann nur einmal verwendet werden.

Backup-Codes neu generierenLink zum Abschnitt kopieren

Erstellen Sie einen neuen Satz von Backup-Codes (macht alle vorherigen Codes ungültig). Erfordert einen aktuellen TOTP-Code:

POST https://api.mail.land/v1/auth/2fa/backup-codes/regenerate

{
  "code": "123456"
}

curl -X POST https://api.mail.land/v1/auth/2fa/backup-codes/regenerate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

[
  "X2Y3Z4A5",
  "B6C7D8E9",
  "F2G3H4J5",
  "K6L7M8N9",
  "P2Q3R4S5",
  "T6U7V8W9",
  "X6Y7Z8A9",
  "B2C3D4E5",
  "F6G7H8J9",
  "K2L3M4N5"
]

Die Antwort ist ein reines JSON-Array von Strings, nicht { "backupCodes": [...] }.

2FA-Status prüfenLink zum Abschnitt kopieren

GET https://api.mail.land/v1/auth/2fa/status

curl https://api.mail.land/v1/auth/2fa/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "isEnabled": true,
  "enabledAt": "2026-01-15T10:00:00Z",
  "backupCodesRemaining": 6,
  "trustedDevicesCount": 2
}

Vertrauenswürdige GeräteLink zum Abschnitt kopieren

Beim Verifizieren der 2FA kann das Gerät gespeichert werden, um die 2FA bei zukünftigen Anmeldungen von demselben Browser zu überspringen.

Vertrauenswürdige Geräte auflistenLink zum Abschnitt kopieren

GET https://api.mail.land/v1/auth/2fa/devices

curl https://api.mail.land/v1/auth/2fa/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "id": "dev_a1b2c3d4e5",
    "deviceName": "Chrome on macOS",
    "ipAddress": "203.0.113.10",
    "createdAt": "2026-01-20T14:00:00Z",
    "expiresAt": "2026-02-19T14:00:00Z",
    "lastUsedAt": "2026-02-17T09:00:00Z",
    "isCurrent": true
  },
  {
    "id": "dev_f6g7h8i9j0",
    "deviceName": "Firefox on Windows",
    "ipAddress": "198.51.100.24",
    "createdAt": "2026-02-01T08:00:00Z",
    "expiresAt": "2026-03-03T08:00:00Z",
    "lastUsedAt": "2026-02-16T15:30:00Z",
    "isCurrent": false
  }
]

Die Antwort ist ein reines Array, nicht { "devices": [...] }, und die Felder sind deviceName, ipAddress, expiresAt und isCurrent statt name.

Gerät widerrufenLink zum Abschnitt kopieren

DELETE https://api.mail.land/v1/auth/2fa/devices/{id}

Liefert bei Erfolg 204, oder 404 RESOURCE_NOT_FOUND, wenn die Geräte-ID nicht dem aktuellen Benutzer gehört.

curl -X DELETE https://api.mail.land/v1/auth/2fa/devices/dev_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Alle Geräte widerrufenLink zum Abschnitt kopieren

DELETE https://api.mail.land/v1/auth/2fa/devices

curl -X DELETE https://api.mail.land/v1/auth/2fa/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Widerruft alle vertrauenswürdigen Geräte, sodass bei der nächsten Anmeldung von jedem Gerät eine 2FA-Verifizierung erforderlich ist.

Eine Passwortänderung, das Zurücksetzen des Passworts und die Abmeldung überall (POST /v1/auth/revoke-all-tokens) widerrufen ebenso alle vertrauenswürdigen Geräte.

2FA deaktivierenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/auth/2fa/disable

{
  "code": "123456"
}

curl -X POST https://api.mail.land/v1/auth/2fa/disable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Erfordert einen gültigen TOTP- oder Backup-Code zur Bestätigung der Aktion: Zuerst wird ein TOTP-Code versucht, ein Backup-Code wird nur akzeptiert, wenn die TOTP-Prüfung fehlschlägt. Das Deaktivieren der 2FA macht alle Backup-Codes und vertrauenswürdige Geräte ungültig.

FehlerantwortenLink zum Abschnitt kopieren

Die meisten Fehlschläge (ungültiger oder abgelaufener Code, falscher Zustand, wiederverwendeter Backup-Code) liefern 400 INVALID_REQUEST mit einer Meldung. Ein fehlerhafter Request-Body (falsche Code-Länge, fehlende challengeId usw.) scheitert zuerst an der Feldvalidierung und liefert stattdessen 400 VALIDATION_FAILED. Ein unbekanntes Gerät liefert 404 RESOURCE_NOT_FOUND. Es gibt keinen separaten Code wie INVALID_CODE, TWO_FACTOR_* oder CHALLENGE_EXPIRED.

Nächste SchritteLink zum Abschnitt kopieren

• Authentifizierung: Anmeldung und Token-Verwaltung
• Team-Verwaltung: Teamzugang verwalten
• Arbeitsbereiche: Arbeitsbereichseinstellungen