Authentication endpoints: login and password reset

These endpoints cover the core login flow for UniMaps: credential-based login that optionally triggers two-factor authentication, a three-step password reset flow (send code → verify code → reset), an alternative login path using a downloaded .jw secure key file, and logout. All responses are JSON. Repeated failed login attempts trigger a 15-minute account lockout tracked server-side per email address.

Authenticates a user with email and password. On success, returns a Sanctum bearer token. If the user has two-factor authentication enabled, the token is withheld and a 2FA code is sent to the registered email instead.

string

required

The user’s registered email address.

password

string

required

The user’s password.

Responses

message

string

Human-readable result message.

token

string

Sanctum bearer token. Present only when login succeeds and 2FA is not required.

two_factor_required

boolean

true when the account has 2FA enabled. No token is returned in this case.

expires_in

integer

Seconds until the 2FA code expires (180 seconds). Present only when two_factor_required is true.

user

object

Basic user data (id, name, email, status). Present only on successful login without 2FA.

blocked

boolean

true when the account is temporarily locked due to repeated failed attempts.

remaining_seconds

integer

Seconds remaining in the lockout period. Present when blocked is true.

remaining_attempts

integer

Failed attempts still allowed before lockout. Present when credentials are wrong but the account is not yet locked.

curl -X POST https://your-api.up.railway.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "student@itfip.edu.co", "password": "secret1234"}'

200 — Login successful

{
  "message": "Login exitoso",
  "token": "1|abc123...",
  "user": {
    "id": 42,
    "name": "María López",
    "email": "student@itfip.edu.co",
    "status": "activo"
  }
}

200 — 2FA required

{
  "message": "Código de autenticación enviado al correo registrado",
  "two_factor_required": true,
  "expires_in": 180
}

401 — Wrong credentials

{
  "message": "Credenciales incorrectas",
  "remaining_attempts": 3
}

403 — Account blocked by admin or unverified email

{ "message": "Tu cuenta ha sido bloqueada. Contacta al administrador." }

429 — Too many failed attempts

{
  "message": "Cuenta bloqueada por 15 minutos debido a múltiples intentos fallidos",
  "blocked": true,
  "remaining_seconds": 900
}

The account is locked for 15 minutes after 5 consecutive failed attempts for an existing email address. Attempts against non-existent email addresses are silently discarded with a generic 401 to prevent user enumeration.

POST /api/auth/forgot-password

Sends a 6-digit numeric reset code to the given email address. The code expires in 15 minutes.

string

required

Email address associated with the account.

Responses

message

string

Confirmation that the code was sent.

string

The address the code was sent to.

curl -X POST https://your-api.up.railway.app/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "student@itfip.edu.co"}'

200 — Code sent

{
  "message": "Código enviado exitosamente",
  "email": "student@itfip.edu.co"
}

422 — Validation error

{
  "message": "The email field is required.",
  "errors": { "email": ["El correo es requerido"] }
}

POST /api/auth/verify-code

Verifies the 6-digit code sent by /api/auth/forgot-password without resetting the password yet. This is step two of the three-step reset flow.

string

required

The account email address.

code

string

required

The 6-digit numeric code from the reset email. Must be exactly 6 characters.

Responses

message

string

"Código verificado" on success.

string

Echoes back the verified email address.

curl -X POST https://your-api.up.railway.app/api/auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{"email": "student@itfip.edu.co", "code": "482910"}'

200 — Code valid

{
  "message": "Código verificado",
  "email": "student@itfip.edu.co"
}

422 — Code wrong or expired

{ "message": "Código incorrecto" }

POST /api/auth/reset-password

Resets the account password. Requires the same verified code from the previous step. This is the final step of the password reset flow.

string

required

The account email address.

code

string

required

The 6-digit reset code. Must be exactly 6 characters.

password

string

required

The new password. Minimum 8 characters.

password_confirmation

string

required

Must match password.

Responses

message

string

"Contraseña actualizada exitosamente" on success.

curl -X POST https://your-api.up.railway.app/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "student@itfip.edu.co",
    "code": "482910",
    "password": "newSecret99",
    "password_confirmation": "newSecret99"
  }'

200 — Password updated

{ "message": "Contraseña actualizada exitosamente" }

422 — Code invalid or expired

{ "message": "Código inválido o expirado" }

Authenticates a user by providing the raw content of their .jw secure key file. The server hashes the provided content and compares it against the stored hash for the account. This is an alternative login path for users who have lost their password.

string

required

The account email address.

secure_key_content

string

required

Full text content of the .jw key file.

Responses

message

string

Human-readable result.

token

string

Sanctum bearer token for the authenticated session.

user

object

Full user model data.

curl -X POST https://your-api.up.railway.app/api/auth/login-with-key \
  -H "Content-Type: application/json" \
  -d '{
    "email": "student@itfip.edu.co",
    "secure_key_content": "<contents of your .jw file>"
  }'

200 — Access granted

{
  "message": "Acceso concedido con clave segura",
  "token": "2|xyz789...",
  "user": { "id": 42, "email": "student@itfip.edu.co" }
}

401 — Key does not match

{ "message": "Archivo de clave segura inválido" }

404 — User not found

{ "message": "Usuario no encontrado o sin clave segura" }

The .jw file can be obtained via GET /api/auth/secure-key-download or requested by email via POST /api/auth/send-secure-key-email. See the Registration endpoints page for details.

POST /api/auth/logout

Revokes the bearer token used in the current request. Requires authentication. Headers

Header	Value
`Authorization`	`Bearer {token}`

Responses

message

string

"Sesión cerrada exitosamente" on success.

curl -X POST https://your-api.up.railway.app/api/auth/logout \
  -H "Authorization: Bearer 1|abc123..."

200 — Logged out

{ "message": "Sesión cerrada exitosamente" }

401 — Missing or invalid token

{ "message": "Unauthenticated." }

Authentication API

Map API

Admin API

Authentication endpoints: login and password reset

Responses

POST /api/auth/forgot-password

Responses

POST /api/auth/verify-code

Responses

POST /api/auth/reset-password

Responses

Responses

POST /api/auth/logout

Responses

Build docs developers (and LLMs) love

Authentication API

Map API

Admin API

Documentation Index

​POST /api/auth/login

​Responses

​POST /api/auth/forgot-password

​Responses

​POST /api/auth/verify-code

​Responses

​POST /api/auth/reset-password

​Responses

​POST /api/auth/login-with-key

​Responses

​POST /api/auth/logout

​Responses

Build docs developers (and LLMs) love

POST /api/auth/login

Responses

POST /api/auth/forgot-password

Responses

POST /api/auth/verify-code

Responses

POST /api/auth/reset-password

Responses

POST /api/auth/login-with-key

Responses

POST /api/auth/logout

Responses