Autenticación

La API usa Bearer Tokens (JWT) para autenticar las peticiones protegidas. Obtén tu token con POST /api/auth/login e inclúyelo en el header Authorization de cada solicitud.

Authorization: Bearer oat_xxxxxxxxxxxxxxxxxxxx

Registro de usuario

POST /api/auth/register
Content-Type: application/json

Body:

{
  "firstName": "Carlos",
  "lastName": "Mendoza",
  "email": "carlos@inmobiliaria.mx",
  "password": "SecurePass123!",
  "phone": "+52 55 1234 5678",
  "role": "agency_admin",
  "acceptedTerms": true
}

acceptedTerms es obligatorio

Debes enviar "acceptedTerms": true para registrarte (consentimiento de los Términos y Condiciones y el Aviso de Privacidad). Si lo omites o lo mandas en false, la API responde 422 con el mensaje "Debes aceptar los Términos y Condiciones y el Aviso de Privacidad".

Roles disponibles:

Rol	Descripción
agency_admin	Administrador de agencia inmobiliaria
agent	Agente inmobiliario (normalmente creado por la agencia)
broker	Broker independiente
developer	Desarrollador inmobiliario
comprador	Usuario comprador / cliente final

Respuesta 201:

{
  "message": "Usuario registrado exitosamente. Por favor, revisa tu correo electrónico para verificar tu cuenta.",
  "requiresEmailVerification": true,
  "emailSent": true,
  "email": "carlos@inmobiliaria.mx",
  "redirectToLogin": true
}

El registro NO devuelve token — requiere verificar el correo

Tras registrarte, la cuenta queda en estado pending y no recibes token todavía. Debes verificar el email antes de poder hacer login. Si intentas POST /api/auth/login con la cuenta sin verificar, obtendrás un 403 con requiresEmailVerification: true. No necesitas abrir el frontend: puedes verificar directamente contra la API con el token del correo — ver Verificar sin pasar por el frontend. El token de acceso (JWT) se obtiene después, en el login, ya con la cuenta verificada.

Login

POST /api/auth/login
Content-Type: application/json

Body:

{
  "email": "carlos@inmobiliaria.mx",
  "password": "SecurePass123!"
}

Respuesta 200:

{
  "status": "success",
  "data": {
    "token": "oat_xxxxxxxxxxxxxxxxxxxx",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "Carlos",
      "lastName": "Mendoza",
      "email": "carlos@inmobiliaria.mx",
      "role": "agency_admin"
    }
  }
}

Obtener perfil del usuario autenticado

GET /api/auth/me
Authorization: Bearer {token}

Respuesta 200:

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "Carlos",
    "lastName": "Mendoza",
    "email": "carlos@inmobiliaria.mx",
    "role": "agency_admin",
    "phone": "+52 55 1234 5678",
    "createdAt": "2026-05-13T10:00:00.000Z"
  }
}

Actualizar perfil

PUT /api/auth/profile
Authorization: Bearer {token}
Content-Type: application/json

Body (todos los campos son opcionales):

{
  "firstName": "Carlos",
  "lastName": "Mendoza López",
  "phone": "+52 55 9999 0000",
  "companyName": "Inmobiliaria Centro MX"
}

Logout

POST /api/auth/logout
Authorization: Bearer {token}

Respuesta 200:

{
  "status": "success",
  "message": "Logged out successfully"
}

Verificación de email

Después del registro, el usuario recibe un correo con un enlace de verificación. Mientras la cuenta no esté verificada, POST /api/auth/login responde 403 con requiresEmailVerification: true.

Verificar sin pasar por el frontend

El enlace del correo apunta al frontend, pero la verificación real la hace la API. Puedes verificar la cuenta directamente (con curl, Postman o cualquier cliente HTTP) sin abrir el navegador.

El token viaja como query param en el enlace del correo:

https://www.havi.app/auth/verify-email?token=ABC123XYZ
                                        ^^^^^^^^^^^^^^^^
                                        este es el token

Toma ese token y llámalo directamente contra la API:

GET /api/auth/verify-email?token={token}

curl 'https://api.havi.app/api/auth/verify-email?token=ABC123XYZ'

Respuesta 200:

{
  "message": "Email verificado exitosamente",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "Carlos",
    "lastName": "Mendoza",
    "email": "carlos@inmobiliaria.mx",
    "role": "agency_admin",
    "status": "active",
    "emailVerified": true
  }
}

Tras esta respuesta la cuenta queda en status: "active" y ya puedes hacer POST /api/auth/login para obtener el token.

Errores posibles:

Código	message	Causa
400	Token de verificación requerido	No se envió el query param token
400	Token de verificación inválido o expirado	El token no existe, ya fue usado o expiró
404	Usuario no encontrado	El token apunta a un usuario inexistente

El token es de un solo uso

Cada token de verificación se marca como usado al verificar. Si necesitas otro (porque expiró o ya se usó), genera uno nuevo con POST /api/auth/resend-verification.

Reenviar el correo de verificación

POST /api/auth/resend-verification
Content-Type: application/json

{
  "email": "carlos@inmobiliaria.mx"
}

Genera un token nuevo y reenvía el correo. Útil si el token anterior expiró o ya fue usado.

OAuth — Login con Google

GET /api/auth/google/redirect

Redirige al usuario a la pantalla de autorización de Google. Después del callback, recibirás el token en:

GET /api/auth/google/callback

Recuperación de contraseña

Solicitar reset:

POST /api/auth/forgot-password
Content-Type: application/json

{
  "email": "carlos@inmobiliaria.mx"
}

Confirmar nuevo password:

POST /api/auth/reset-password
Content-Type: application/json

{
  "token": "reset_token_del_correo",
  "password": "NuevoPass456!"
}