Autenticación de Dos Factores

Añada una capa adicional de seguridad a su cuenta de MailLand con la autenticación de dos factores basada en TOTP. Una vez activada, el inicio de sesión requiere tanto su contraseña como un código temporal generado por una aplicación de autenticación.

Configurar la 2FACopiar enlace de la sección

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

Verificar un códigoCopiar enlace de la sección

Cuando el inicio de sesión devuelve requiresTwoFactor: true, complete la autenticación verificando un código TOTP:

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

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

trustDevice es opcional. Si es true, el dispositivo se recuerda durante 30 días y la 2FA se omite en inicios de sesión posteriores desde él.

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
}

No hay expiresIn ni un objeto user en esta respuesta. deviceTrusted es true cuando trustDevice fue true. El token del dispositivo nunca va en el cuerpo: la API lo establece como la cookie HttpOnly __Host-trusted_device, y el navegador lo envía en el siguiente inicio de sesión.

Usar un código de respaldoCopiar enlace de la sección

Si pierde el acceso a su aplicación de autenticación, utilice un código de respaldo en su lugar:

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

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

El campo es code (8–10 caracteres), no 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"
  }'

Devuelve la misma respuesta que la verificación TOTP. Cada código de respaldo solo puede utilizarse una vez.

Regenerar códigos de respaldoCopiar enlace de la sección

Genere un nuevo conjunto de códigos de respaldo (invalida todos los códigos anteriores). Requiere un código TOTP actual:

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 respuesta es un arreglo JSON simple de cadenas, no { "backupCodes": [...] }.

Verificar el estado de la 2FACopiar enlace de la sección

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
}

Dispositivos de confianzaCopiar enlace de la sección

Al verificar la 2FA, el dispositivo puede recordarse para omitir la 2FA en futuros inicios de sesión desde el mismo navegador.

Listar dispositivos de confianzaCopiar enlace de la sección

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 respuesta es un arreglo simple, no { "devices": [...] }, y los campos son deviceName, ipAddress, expiresAt e isCurrent en lugar de name.

Revocar un dispositivoCopiar enlace de la sección

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

Devuelve 204 en caso de éxito, o 404 RESOURCE_NOT_FOUND si el id del dispositivo no pertenece al usuario actual.

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

Revocar todos los dispositivosCopiar enlace de la sección

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

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

Revoca todos los dispositivos de confianza, requiriendo verificación 2FA en el próximo inicio de sesión desde cada dispositivo.

Cambiar la contraseña, restablecerla y cerrar la sesión en todas partes (POST /v1/auth/revoke-all-tokens) también revocan todos los dispositivos de confianza, del mismo modo.

Deshabilitar la 2FACopiar enlace de la sección

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

Requiere un código TOTP o de respaldo válido para confirmar la acción: primero se intenta un código TOTP, y un código de respaldo solo se acepta si la verificación TOTP falla. Deshabilitar la 2FA invalida todos los códigos de respaldo y dispositivos de confianza.

Respuestas de errorCopiar enlace de la sección

La mayoría de los fallos (código inválido o expirado, estado incorrecto, código de respaldo reutilizado) devuelven 400 INVALID_REQUEST con un mensaje. Un cuerpo de solicitud malformado (longitud de código incorrecta, challengeId faltante, etc.) falla primero la validación de campos y devuelve 400 VALIDATION_FAILED en su lugar. Un dispositivo desconocido devuelve 404 RESOURCE_NOT_FOUND. No existe un código separado como INVALID_CODE, TWO_FACTOR_* o CHALLENGE_EXPIRED.

Pasos siguientesCopiar enlace de la sección

• Autenticación: inicio de sesión y gestión de tokens
• Gestión de equipo: gestionar el acceso del equipo
• Espacios de trabajo: configuración del espacio de trabajo