Authentication Endpoints — /api/auth Routes Reference

The Eco-It authentication system uses a two-step email-verification flow for new registrations, JWT-based sessions for all protected routes, and a Google OAuth 2.0 integration for single-sign-on. Password recovery is handled through a six-digit code delivered by email. All auth endpoints are rate-limited; exceeding the limit returns 429 Too Many Requests.

JWTs are returned in the response body — not in cookies. Store the token in localStorage or a secure in-memory store and attach it as Authorization: Bearer <token> on every protected request.

Registration flow

User registration is a two-step process: first the server sends a verification code to the supplied email address, then the client submits that code to finalise account creation.

POST /api/auth/enviar-codigo-registro   ← Step 1: request verification code
POST /api/auth/verificar-registro       ← Step 2: verify code → account created
POST /api/auth/reenviar-codigo-registro ← Resend code (3-minute cooldown)

POST /api/auth/registro is present in the router but is a deprecated stub. It always returns HTTP 400 with the message "Usa el flujo de verificación por email: /enviar-codigo-registro → /verificar-registro". Do not use this route — use the two-step flow documented below.

POST `/api/auth/enviar-codigo-registro`

Validates the supplied data, checks for duplicate emails, hashes the password, and sends a 6-digit OTP to the provided email address. The pending registration is stored for 15 minutes. Returns 429 if a code was already sent in the last 3 minutes. Request body

nombre

string

required

First name of the user. Must be between 2 and 50 characters.

apellido

string

required

Last name / surname of the user.

edad

number

required

Age of the user. Must be a positive integer.

string

required

Valid email address. Must not already be registered.

telefono

string

required

Mobile phone number (validated format).

password

string

required

Plain-text password. Minimum 8 characters. Hashed with bcrypt (cost 12) before persisting.

Responses

success

boolean

true on success.

mensaje

string

Human-readable confirmation: "Código enviado a tu correo electrónico.".

curl -X POST https://api.eco-it.app/api/auth/enviar-codigo-registro \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Valentina",
    "apellido": "Ríos",
    "edad": 28,
    "email": "valentina@example.com",
    "telefono": "3001234567",
    "password": "MiClave2024!"
  }'

{ "success": true, "mensaje": "Código enviado a tu correo electrónico." }

If the email cannot be delivered (e.g. invalid address or SMTP failure), the pending registration is not saved and the endpoint returns 500. No retry cooldown applies in this case.

POST `/api/auth/verificar-registro`

Verifies the 6-digit code against the pending registration record. On success the user account is created in the database, a welcome email is dispatched, and a 7-day JWT is returned. Allows a maximum of 5 incorrect attempts before the pending record is discarded. Request body

string

required

The same email address used in enviar-codigo-registro.

codigo

string

required

The 6-digit verification code received by email.

Responses

success

boolean

true on successful verification and account creation.

mensaje

string

"¡Cuenta verificada y creada exitosamente!"

data.token

string

Signed JWT. Expires in 7 days. Payload: { id, rol, perfilCompleto }.

data.usuario

object

Newly created user object.

data.usuario.id

string

MongoDB _id of the user.

data.usuario.nombre

string

data.usuario.apellido

string

data.usuario.email

string

data.usuario.telefono

string

data.usuario.edad

number

data.usuario.rol

string

Always "user" for newly registered accounts.

data.usuario.perfilCompleto

boolean

true — email-registered users always have a complete profile.

curl -X POST https://api.eco-it.app/api/auth/verificar-registro \
  -H "Content-Type: application/json" \
  -d '{ "email": "valentina@example.com", "codigo": "482910" }'

{
  "success": true,
  "mensaje": "¡Cuenta verificada y creada exitosamente!",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "usuario": {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "nombre": "Valentina",
      "apellido": "Ríos",
      "email": "valentina@example.com",
      "telefono": "3001234567",
      "edad": 28,
      "rol": "user",
      "perfilCompleto": true
    }
  }
}

POST `/api/auth/reenviar-codigo-registro`

Issues a fresh 6-digit code for an existing pending registration. Enforces a 3-minute cooldown between sends and resets the 15-minute expiry window. Request body

string

required

Email address of the pending registration.

Responses

success

boolean

mensaje

string

"Nuevo código enviado a tu correo." on success.

curl -X POST https://api.eco-it.app/api/auth/reenviar-codigo-registro \
  -H "Content-Type: application/json" \
  -d '{ "email": "valentina@example.com" }'

{ "success": true, "mensaje": "Nuevo código enviado a tu correo." }

Authenticates a local (email + password) user and returns a 12-hour JWT.

Users who registered via Google OAuth do not have a password. Attempting to log in with their email returns 401 with the message "Este usuario se registró con Google.".

Request body

string

required

Registered email address.

password

string

required

Plain-text password.

Responses

message

string

"Inicio de sesión correcto" on success.

data.token

string

Signed JWT. Expires in 12 hours.

data.usuario

object

Authenticated user object — same shape as the registration response.

curl -X POST https://api.eco-it.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "valentina@example.com", "password": "MiClave2024!" }'

{
  "message": "Inicio de sesión correcto",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "usuario": {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "nombre": "Valentina",
      "apellido": "Ríos",
      "edad": 28,
      "email": "valentina@example.com",
      "telefono": "3001234567",
      "rol": "user",
      "perfilCompleto": true
    }
  }
}

POST `/api/auth/logout`

Signals the client to discard the JWT. Since tokens are stored client-side, this endpoint simply returns a success acknowledgement — no server-side state is invalidated. Request body — none required. Response

success

boolean

Always true.

message

string

"Sesión cerrada correctamente".

curl -X POST https://api.eco-it.app/api/auth/logout

{ "success": true, "message": "Sesión cerrada correctamente" }

Google OAuth

GET `/api/auth/google`

Initiates the Google OAuth 2.0 consent flow. Redirects the browser to Google’s authorisation page requesting the profile and email scopes. This endpoint is visited directly by the browser — it is not called with fetch or XMLHttpRequest. No request body. No authentication required.

Open this URL in a new browser tab or window, or set window.location.href from the frontend.

GET `/api/auth/google/callback`

Handles the OAuth callback from Google. On success, generates a 12-hour JWT and returns an HTML page that redirects the browser to:

{FRONT_URL}/auth/google/success?token=<jwt>

The frontend must read the token query parameter and store it for subsequent API calls. On failure, the browser is redirected to {FRONT_URL}/login. No request body. Managed entirely by Passport.js and the browser redirect cycle.

Profile completion (Google OAuth users)

PUT `/api/auth/completar-perfil`

Google OAuth users land with perfilCompleto: false. This endpoint lets them supply the remaining fields before accessing the full application. Authentication: Authorization: Bearer <token> required. Request body

apellido

string

required

Last name. Must not be empty.

edad

number

required

Age. Must be an integer between 1 and 120.

telefono

string

required

Mobile phone number in a valid format.

Responses

success

boolean

usuario

object

The full updated user document from MongoDB.

curl -X PUT https://api.eco-it.app/api/auth/completar-perfil \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "apellido": "Ríos", "edad": 28, "telefono": "3001234567" }'

{
  "success": true,
  "usuario": {
    "_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "nombre": "Valentina",
    "apellido": "Ríos",
    "email": "valentina@gmail.com",
    "telefono": "3001234567",
    "edad": 28,
    "rol": "user",
    "perfilCompleto": true
  }
}

Password recovery flow

Password recovery is a three-step process using a 6-digit email code.

Request a recovery code

POST /api/auth/recuperar-password — sends the code to the user’s registered email.

Verify the code

POST /api/auth/recuperar-password/verificar — confirms the code is valid before letting the user type a new password.

Set a new password

POST /api/auth/recuperar-password/restablecer — applies the new password and invalidates the recovery token.

If the user never received the code, POST /api/auth/recuperar-password/reenviar issues a fresh one (3-minute cooldown).

POST `/api/auth/recuperar-password`

Looks up the account by email, generates a 6-digit code (SHA-256 hashed before storage), and emails it to the user. Code expires in 15 minutes. Request body

string

required

Email address of the account to recover.

curl -X POST https://api.eco-it.app/api/auth/recuperar-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "valentina@example.com" }'

{ "success": true, "mensaje": "Código enviado a tu correo electrónico" }

POST `/api/auth/recuperar-password/verificar`

Confirms that the provided code is valid and unexpired. Use this step to gate the “new password” form in the UI — it does not change the password. Request body

string

required

Account email address.

codigo

string

required

The 6-digit code received by email.

curl -X POST https://api.eco-it.app/api/auth/recuperar-password/verificar \
  -H "Content-Type: application/json" \
  -d '{ "email": "valentina@example.com", "codigo": "748201" }'

{ "success": true, "mensaje": "Código válido" }

POST `/api/auth/recuperar-password/reenviar`

Issues a new 6-digit code and resets the 15-minute expiry. Enforces a 3-minute cooldown between resends. Request body

string

required

Account email address.

curl -X POST https://api.eco-it.app/api/auth/recuperar-password/reenviar \
  -H "Content-Type: application/json" \
  -d '{ "email": "valentina@example.com" }'

{ "success": true, "mensaje": "Nuevo código enviado a tu correo electrónico" }

POST `/api/auth/recuperar-password/restablecer`

Final step of password recovery. Verifies the code one more time, updates the password (the model’s pre('save') hook hashes it automatically), and clears the recovery token fields. Request body

string

required

Account email address.

codigo

string

required

The 6-digit code from the recovery email.

password

string

required

New plain-text password. Minimum 8 characters.

Response

success

boolean

mensaje

string

"Contraseña actualizada correctamente" on success.

curl -X POST https://api.eco-it.app/api/auth/recuperar-password/restablecer \
  -H "Content-Type: application/json" \
  -d '{
    "email": "valentina@example.com",
    "codigo": "748201",
    "password": "NuevaClave2024!"
  }'

{ "success": true, "mensaje": "Contraseña actualizada correctamente" }

Error reference

HTTP Status	Cause
`400`	Missing or invalid fields; duplicate email; expired or incorrect OTP; max OTP attempts reached
`401`	Wrong credentials; Google-only account attempted with password login
`404`	Email not found in the system
`429`	Rate limit exceeded (auth limiter) or resend cooldown active
`500`	Internal server error; SMTP delivery failure

Overview

Endpoints

Authentication Endpoints — /api/auth Routes Reference

Registration flow

POST `/api/auth/enviar-codigo-registro`

POST `/api/auth/verificar-registro`

POST `/api/auth/reenviar-codigo-registro`

POST `/api/auth/logout`

Google OAuth

GET `/api/auth/google`

GET `/api/auth/google/callback`

Profile completion (Google OAuth users)

PUT `/api/auth/completar-perfil`

Password recovery flow

POST `/api/auth/recuperar-password`

POST `/api/auth/recuperar-password/verificar`

POST `/api/auth/recuperar-password/reenviar`

POST `/api/auth/recuperar-password/restablecer`

Error reference

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Registration flow

​POST /api/auth/enviar-codigo-registro

​POST /api/auth/verificar-registro

​POST /api/auth/reenviar-codigo-registro

​Login & Logout

​POST /api/auth/login

​POST /api/auth/logout

​Google OAuth

​GET /api/auth/google

​GET /api/auth/google/callback

​Profile completion (Google OAuth users)

​PUT /api/auth/completar-perfil

​Password recovery flow

​POST /api/auth/recuperar-password

​POST /api/auth/recuperar-password/verificar

​POST /api/auth/recuperar-password/reenviar

​POST /api/auth/recuperar-password/restablecer

​Error reference

Build docs developers (and LLMs) love

Registration flow

POST `/api/auth/enviar-codigo-registro`

POST `/api/auth/verificar-registro`

POST `/api/auth/reenviar-codigo-registro`

Login & Logout

POST `/api/auth/login`

POST `/api/auth/logout`

Google OAuth

GET `/api/auth/google`

GET `/api/auth/google/callback`

Profile completion (Google OAuth users)

PUT `/api/auth/completar-perfil`

Password recovery flow

POST `/api/auth/recuperar-password`

POST `/api/auth/recuperar-password/verificar`

POST `/api/auth/recuperar-password/reenviar`

POST `/api/auth/recuperar-password/restablecer`

Error reference