Authentification à deux facteurs

Ajoutez une couche de sécurité supplémentaire à votre compte MailLand grâce à l'authentification à deux facteurs basée sur TOTP. Une fois activée, la connexion requiert à la fois votre mot de passe et un code temporel généré par une application d'authentification.

Configurer la 2FACopier le lien de la section

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"
}

Vérifier un codeCopier le lien de la section

Lorsque la connexion renvoie requiresTwoFactor: true, finalisez l'authentification en vérifiant un code TOTP :

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

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

trustDevice est facultatif. Lorsqu'il est true, l'appareil est mémorisé pendant 30 jours et la 2FA est ignorée lors des connexions suivantes depuis cet appareil.

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
}

Il n'y a pas de expiresIn ni d'objet user dans cette réponse. deviceTrusted vaut true lorsque trustDevice valait true. Le jeton de l'appareil n'est jamais dans le corps : l'API le dépose dans le cookie HttpOnly __Host-trusted_device, et le navigateur l'envoie à la connexion suivante.

Utiliser un code de secoursCopier le lien de la section

Si vous perdez l'accès à votre application d'authentification, utilisez un code de secours à la place :

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

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

Le champ est code (8 à 10 caractères), pas 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"
  }'

Retourne la même réponse que la vérification TOTP. Chaque code de secours ne peut être utilisé qu'une seule fois.

Régénérer les codes de secoursCopier le lien de la section

Générez un nouveau jeu de codes de secours (invalide tous les codes précédents). Nécessite un code TOTP actuel :

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"
]

La réponse est un tableau JSON brut de chaînes, pas { "backupCodes": [...] }.

Vérifier le statut de la 2FACopier le lien de la section

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
}

Appareils de confianceCopier le lien de la section

Lors de la vérification 2FA, l'appareil peut être mémorisé afin d'éviter la 2FA lors des prochaines connexions depuis le même navigateur.

Lister les appareils de confianceCopier le lien de la section

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
  }
]

La réponse est un tableau brut, pas { "devices": [...] }, et les champs sont deviceName, ipAddress, expiresAt et isCurrent plutôt que name.

Révoquer un appareilCopier le lien de la section

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

Renvoie 204 en cas de succès, ou 404 RESOURCE_NOT_FOUND si l'id d'appareil n'appartient pas à l'utilisateur courant.

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

Révoquer tous les appareilsCopier le lien de la section

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

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

Révoque tous les appareils de confiance, exigeant une vérification 2FA lors de la prochaine connexion depuis chaque appareil.

Changer le mot de passe, le réinitialiser et se déconnecter partout (POST /v1/auth/revoke-all-tokens) révoquent aussi tous les appareils de confiance, de la même manière.

Désactiver la 2FACopier le lien de la section

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"}'

Nécessite un code TOTP ou un code de secours valide pour confirmer l'action : un code TOTP est essayé en premier, et un code de secours n'est accepté que si la vérification TOTP échoue. La désactivation de la 2FA invalide tous les codes de secours et les appareils de confiance.

Réponses d'erreurCopier le lien de la section

La plupart des échecs (code invalide ou expiré, état incorrect, code de secours réutilisé) renvoient 400 INVALID_REQUEST avec un message. Un corps de requête malformé (longueur de code incorrecte, challengeId manquant, etc.) échoue d'abord à la validation des champs et renvoie plutôt 400 VALIDATION_FAILED. Un appareil inconnu renvoie 404 RESOURCE_NOT_FOUND. Il n'existe pas de code séparé comme INVALID_CODE, TWO_FACTOR_* ou CHALLENGE_EXPIRED.

Étapes suivantesCopier le lien de la section

• Authentification : connexion et gestion des tokens
• Gestion d'équipe : gérer l'accès de l'équipe
• Espaces de travail : paramètres de l'espace de travail