MELIKA Authentication API: Register, Login & Recovery

MELIKA uses JWT Bearer tokens for authentication. All /auth/* endpoints are public — no token is required to register, log in, or recover a password. Once logged in, include the token in every request to a protected route via the Authorization header. Tokens carry a minimal payload (id, nombre, rol) and expire after 8 hours.

Authorization: Bearer <token>

The decoded JWT payload has the following shape:

{
  "id": 42,
  "nombre": "María",
  "rol": "paciente"
}

POST /auth/register

Registers a new user account. The account is created with activo = FALSE and verificado = FALSE. A 6-digit verification code is emailed to the provided address and expires in 15 minutes. The user must verify their email before they can log in. Authentication required: No

Request body

nombre

string

required

First name of the user. Must be at least 2 characters. Only letters, spaces, hyphens, and apostrophes are allowed — numbers and purely repeated characters are rejected.

primer_apellido

string

required

First surname of the user. Same character rules as nombre.

string

required

Unique email address. Used as the login identifier and for sending verification codes. Must match the format local@domain.tld.

password

string

required

Account password. Minimum 6 characters. A password composed entirely of one repeated character (e.g. "aaaaaa") must be at least 8 characters to avoid being rejected as too weak.

tipo_documento

string

required

Type of identity document. Accepted values: CC, CE, or PASAPORTE.

numero_documento

string

required

Unique document number. Must contain only digits, between 5 and 15 digits in length. Returns 409 if already registered.

fecha_nacimiento

string

required

Date of birth in YYYY-MM-DD format. Must be a valid past date; the calculated age must fall between 0 and 120 years.

genero

string

required

Gender of the user. Accepted values: M (Male), F (Female), or O (Other).

Responses

mensaje

string

Human-readable confirmation message.

string

The email address to which the verification code was sent.

correoEnviado

boolean

true if the verification email was dispatched successfully.

Error responses

Status	Condition	Body
`422`	Validation failed	`{ mensaje, errores[] }`
`409`	Email already registered	`{ mensaje: "Este correo ya está registrado." }`
`409`	Document number already registered	`{ mensaje: "Este número de documento ya está registrado." }`

If the verification email doesn’t arrive within a few minutes, call POST /auth/reenviar-codigo with tipo: "registro" to request a fresh code.

Example

curl -X POST https://your-api.railway.app/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "María",
    "primer_apellido": "García",
    "email": "maria@example.com",
    "password": "SuperSegura123",
    "tipo_documento": "CC",
    "numero_documento": "1234567890",
    "fecha_nacimiento": "1995-06-15",
    "genero": "F"
  }'

{
  "mensaje": "Cuenta creada. Revisa tu correo para obtener el código de verificación.",
  "email": "maria@example.com",
  "correoEnviado": true
}

Authenticates a registered and verified user. Returns a signed JWT valid for 8 hours and a brief user object. Accounts that exist but have not completed email verification are rejected with a distinct flag so your front-end can prompt the user to verify. Authentication required: No

Request body

string

required

The email address used during registration.

password

string

required

The account password.

Responses

token

string

Signed JWT. Include this as Authorization: Bearer <token> on all protected requests. Expires in 8 h.

usuario

object

Show usuario fields

number

Internal numeric user ID.

nombre

string

User’s first name.

primer_apellido

string

User’s first surname.

string

User’s email address.

rol

string

Role assigned to the account: paciente, medico, or admin.

Error responses

Status	Condition	Body
`401`	Wrong email or password	`{ mensaje: "Correo o contraseña incorrectos." }`
`403`	Email not yet verified	`{ mensaje: "Debes verificar tu cuenta primero. Revisa tu correo.", sinVerificar: true, email }`
`403`	Account is inactive	`{ mensaje: "Tu cuenta está desactivada. Contacta soporte." }`

Example

curl -X POST https://your-api.railway.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria@example.com",
    "password": "SuperSegura123"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "usuario": {
    "id": 42,
    "nombre": "María",
    "primer_apellido": "García",
    "email": "maria@example.com",
    "rol": "paciente"
  }
}

GET /auth/verify-code

Verifies the 6-digit code sent during registration. On success the account is activated (activo = TRUE, verificado = TRUE) and the user may log in immediately. Authentication required: No

Query parameters

string

required

The email address associated with the account being verified.

codigo

string

required

The 6-digit verification code received by email.

Responses

mensaje

string

"Cuenta verificada correctamente. Ya puedes iniciar sesión." on success.

Error responses

Status	Condition	Body
`400`	Code is wrong or not found	`{ mensaje: "Código incorrecto. Verifica e intenta de nuevo." }`
`400`	Code has expired	`{ mensaje: "El código expiró. Solicita uno nuevo.", expirado: true }`

Example

curl "https://your-api.railway.app/auth/verify-code?email=maria@example.com&codigo=483921"

{
  "mensaje": "Cuenta verificada correctamente. Ya puedes iniciar sesión."
}

POST /auth/reenviar-codigo

Generates a new 6-digit code and sends it to the given email, replacing any existing code. Supports both the registration flow (tipo: "registro") and the password-recovery flow (tipo: "recuperacion"). Authentication required: No

Request body

string

required

The email address to which the new code should be sent.

tipo

string

Purpose of the code. Must be "registro" or "recuperacion". Defaults to "registro" if omitted.

Responses

mensaje

string

Confirmation that a new code has been sent.

correoEnviado

boolean

true if the email was dispatched successfully.

Error responses

Status	Condition	Body
`404`	Email not found	`{ mensaje: "No existe una cuenta con este correo." }`
`400`	Account is already verified	`{ mensaje: "Esta cuenta ya fue verificada." }`

Example

curl -X POST https://your-api.railway.app/auth/reenviar-codigo \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria@example.com",
    "tipo": "registro"
  }'

{
  "mensaje": "Código reenviado. Revisa tu correo.",
  "correoEnviado": true
}

POST /auth/recuperar-password

Initiates a password-recovery flow. If the supplied email belongs to a registered active account, a 6-digit recovery code is sent. The response is intentionally identical whether the email exists or not, preventing account enumeration. Authentication required: No

This endpoint always returns the same success message regardless of whether the email is in the database. This is a deliberate security measure to prevent attackers from discovering which addresses are registered (account-enumeration protection). Your front-end should display the message as-is without inferring account existence.

Request body

string

required

The email address for which the recovery code should be sent.

Responses

mensaje

string

Always "Si el correo está registrado, recibirás un código en breve.".

Example

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

{
  "mensaje": "Si el correo está registrado, recibirás un código en breve."
}

POST /auth/nueva-password

Completes the password-recovery flow. Validates the 6-digit code from the recovery email and updates the account password. The code must not be expired. Authentication required: No

Request body

string

required

The email address of the account being recovered.

codigo

string

required

The 6-digit code received via email after calling /auth/recuperar-password.

nueva_password

string

required

The new password. Must be at least 6 characters long.

Responses

mensaje

string

"Contraseña actualizada correctamente. Ya puedes iniciar sesión." on success.

Error responses

Status	Condition	Body
`400`	Missing fields	`{ mensaje: "Todos los campos son obligatorios." }`
`400`	`nueva_password` shorter than 6 characters	`{ mensaje: "La contraseña debe tener mínimo 6 caracteres." }`
`400`	Code is wrong or not found	`{ mensaje: "Código incorrecto o inválido." }`
`400`	Code has expired	`{ mensaje: "El código expiró. Solicita uno nuevo.", expirado: true }`

Example

curl -X POST https://your-api.railway.app/auth/nueva-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria@example.com",
    "codigo": "748201",
    "nueva_password": "NuevaSegura456"
  }'

{
  "mensaje": "Contraseña actualizada correctamente. Ya puedes iniciar sesión."
}

Authentication

Appointments

Doctors & Schedules

Clinical Records

Catalog

Admin

MELIKA Authentication API: Register, Login & Recovery

POST /auth/register

Request body

Responses

Error responses

Example

Request body

Responses

Error responses

Example

GET /auth/verify-code

Query parameters

Responses

Error responses

Example

POST /auth/reenviar-codigo

Request body

Responses

Error responses

Example

POST /auth/recuperar-password

Request body

Responses

Example

POST /auth/nueva-password

Request body

Responses

Error responses

Example

Build docs developers (and LLMs) love

Authentication

Appointments

Doctors & Schedules

Clinical Records

Catalog

Admin

Documentation Index

​POST /auth/register

​Request body

​Responses

​Error responses

​Example

​POST /auth/login

​Request body

​Responses

​Error responses

​Example

​GET /auth/verify-code

​Query parameters

​Responses

​Error responses

​Example

​POST /auth/reenviar-codigo

​Request body

​Responses

​Error responses

​Example

​POST /auth/recuperar-password

​Request body

​Responses

​Example

​POST /auth/nueva-password

​Request body

​Responses

​Error responses

​Example

Build docs developers (and LLMs) love

POST /auth/register

Request body

Responses

Error responses

Example

POST /auth/login

Request body

Responses

Error responses

Example

GET /auth/verify-code

Query parameters

Responses

Error responses

Example

POST /auth/reenviar-codigo

Request body

Responses

Error responses

Example

POST /auth/recuperar-password

Request body

Responses

Example

POST /auth/nueva-password

Request body

Responses

Error responses

Example