Authentication API — register, login, verify, logout

The Authentication API handles the full identity lifecycle for Gestor Deportivo users: creating accounts, verifying them by email, signing in to receive a JWT, and signing out. A separate Password Recovery section documents the two-step code-based flow for resetting a forgotten password. All paths below are relative to your server base URL (e.g. http://localhost:3000). Unless noted, none of these endpoints require a token.

All endpoints in this API use the POST HTTP method. There are no GET, PUT, PATCH, or DELETE routes. The authentication token — where required — must be sent in the access-token request header, not as an Authorization: Bearer header.

POST /api/user/register

Register a new user account. The request must be sent as multipart/form-data because an optional avatar image can be uploaded at registration time. On success, a 5-digit verification code is sent to the supplied email address. The account remains inactive until that code is confirmed via /api/user/verify-accounts. Default values assigned at registration

Field	Default
`roles`	`[{ name: "Usuario", value: "1" }]`
`activate`	`[{ name: "Inactivo", value: "2" }]`
`membership`	`"Plan Gratis"`
`academyOrClub`	`"Sin academia o club"`

Request

Content-Type must be multipart/form-data.

Body fields

firstName

string

required

User’s first name.

lastName

string

required

User’s last name.

string

required

Email address. Stored in lowercase. Must be unique across all accounts.

password

string

required

Plain-text password. Hashed with bcrypt before storage.

sex

string

required

Gender. Must be one of "Masculino", "Femenino", or "Otro".

File upload (optional)

avatar

file

Profile image. Any common image format (JPEG, PNG, WebP). Stored in storage/OauthUser/.

Example

curl -X POST http://localhost:3000/api/user/register \
  -F "firstName=Carlos" \
  -F "lastName=Gómez" \
  -F "email=carlos@example.com" \
  -F "password=supersecret" \
  -F "sex=Masculino" \
  -F "avatar=@/path/to/photo.jpg"

Response

200 — Created

{
  "message": "Cuenta creada correctamente",
  "status": true,
  "saveUser": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "firstName": "Carlos",
    "lastName": "Gómez",
    "email": "carlos@example.com",
    "sex": "Masculino",
    "avatar": ["https://storage.example.com/OauthUser/12photo.jpg"],
    "roles": [{ "name": "Usuario", "value": "1" }],
    "activate": [{ "name": "Inactivo", "value": "2" }],
    "login_code": "31452"
  }
}

message

string

Human-readable result message.

status

boolean

true on success.

saveUser

object

The newly created user document.

Show saveUser fields

saveUser._id

string

MongoDB ObjectId of the new user.

saveUser.firstName

string

Registered first name.

saveUser.lastName

string

Registered last name.

saveUser.email

string

Registered email (lowercase).

saveUser.sex

string

Gender value provided at registration.

saveUser.avatar

array

Array of avatar image URL strings. Empty array if no file was uploaded.

saveUser.roles

array

Array of role objects. Default: [{ name: "Usuario", value: "1" }].

saveUser.activate

array

Activation state. Default: [{ name: "Inactivo", value: "2" }]. Changes to active after email verification.

The 5-digit verification code sent to the user’s email. Shown here for convenience during development; do not expose in production UIs.

Error responses

HTTP status	Condition
`202`	One or more required fields (`firstName`, `lastName`, `email`, `password`, `sex`) are missing.
`200` with `status: false`	The email address is already registered.

POST /api/user/verify-accounts

Activate a newly registered account by submitting the 5-digit code delivered to the user’s email. Once verified, the account’s activate field is updated to [{ name: "1", value: "Activo" }] and the user can log in.

Request

string

required

The email address of the account to activate.

code

string

required

The 5-digit verification code received in the registration email.

Example

curl -X POST http://localhost:3000/api/user/verify-accounts \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carlos@example.com",
    "code": "31452"
  }'

Response

200 — Verified

{
  "message": "Cuenta confirmada correctamente. Inicia sesión para poder disfrutar más de nuestro contenido",
  "status": true
}

message

string

Confirmation message.

status

boolean

true on successful verification.

Error responses

HTTP status	Condition
`203`	Code does not match the stored `login_code`, or the email was not found.

Authenticate a verified user and receive a JWT valid for 365 days. The token must be included in the access-token header for all protected routes.

Request

string

required

The user’s registered email address.

password

string

required

The user’s plain-text password (compared against the bcrypt hash).

Example

curl -X POST http://localhost:3000/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carlos@example.com",
    "password": "supersecret"
  }'

Response

200 — Authenticated

{
  "message": "Bienvenido!",
  "status": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "usuario": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "firstName": "Carlos",
    "lastName": "Gómez",
    "email": "carlos@example.com",
    "avatar": ["https://storage.example.com/OauthUser/12photo.jpg"],
    "sex": "Masculino",
    "idTeam": [],
    "idPlayer": "",
    "roles": [{ "name": "Usuario", "value": "1" }],
    "activate": [{ "name": "1", "value": "Activo" }]
  }
}

token

string

Signed JWT. Pass this value in the access-token header on every protected request.

usuario

object

Snapshot of the authenticated user’s profile.

Show usuario fields

usuario.id

string

MongoDB ObjectId string.

usuario.firstName

string

First name.

usuario.lastName

string

Last name.

usuario.email

string

Email address.

usuario.avatar

array

Array of avatar image URL strings.

usuario.sex

string

Gender: "Masculino", "Femenino", or "Otro".

usuario.idTeam

array

Array of team IDs the user belongs to.

usuario.idPlayer

string

Associated player document ID (empty string if none).

usuario.roles

array

Array of role objects { name, value }. See the Roles table in the Users API reference.

usuario.activate

array

Account activation state array.

Error responses

HTTP status	Condition
`203`	Email not found in the database, or password is incorrect.
`403`	Account has not been activated via the verification code.

POST /api/user/logout

Invalidate the current session by clearing the stored JWT token on the user document. The client should also discard the token locally after calling this endpoint.

Request

string

required

The email address of the account to log out.

Example

curl -X POST http://localhost:3000/api/user/logout \
  -H "Content-Type: application/json" \
  -d '{ "email": "carlos@example.com" }'

Response

200 — Logged out

{
  "message": "Vuelve pronto",
  "status": true
}

message

string

Farewell message.

status

boolean

true on success.

Error responses

HTTP status	Condition
`404`	No user with that email address was found.

Password Recovery

The password recovery flow is a two-step process: first request a reset code, then submit that code alongside the new password. Neither step requires an active session — however, recovery-pass does require a valid access-token header.

POST /api/user/recovery-pass

Initiate a password reset. Generates a 5-digit code, saves it to the user record as code_newpass, and dispatches it to the user’s email address.

This is the only auth-adjacent endpoint that requires the access-token header.

Request

Headers

Header	Value
`access-token`	Valid JWT from login

string

required

The email address of the account for which to initiate a password reset.

Example

curl -X POST http://localhost:3000/api/user/recovery-pass \
  -H "Content-Type: application/json" \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{ "email": "carlos@example.com" }'

Response

200 — Code sent

{
  "message": "Te hemos enviado un código de 5 digitos para verificar el cambio de contraseña",
  "status": true
}

message

string

Confirmation that the code was dispatched.

status

boolean

true on success.

Error responses

HTTP status	Condition
`203`	No account found for the supplied email address.

POST /api/user/update-password

Complete a password reset using the 5-digit code received via email. This endpoint does not require an access-token header — it is designed to be used when the user is locked out.

Request

string

required

The email address of the account being reset.

code_confirm_pass

string

required

The 5-digit code received in the password-recovery email.

newPassword

string

required

The desired new password. Will be hashed with bcrypt before storage.

Example

curl -X POST http://localhost:3000/api/user/update-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carlos@example.com",
    "code_confirm_pass": "24135",
    "newPassword": "newSupersecret!"
  }'

Response

200 — Password updated

{
  "message": "Tu contraseña ha sido cambiada exitosamente",
  "status": true
}

message

string

Confirmation message.

status

boolean

true on success.

Error responses

HTTP status	Condition
`404`	No account found for the supplied email.
`400`	The submitted code does not match the stored `code_newpass`.

The following shell script walks through the complete onboarding flow for a new user.

# ── Step 1: Register ──────────────────────────────────────────────────────────
REGISTER=$(curl -s -X POST http://localhost:3000/api/user/register \
  -F "firstName=Ana" \
  -F "lastName=Torres" \
  -F "email=ana@example.com" \
  -F "password=mypassword" \
  -F "sex=Femenino")

echo "Register response:"
echo $REGISTER | jq .

# The API sends a 5-digit code to ana@example.com.
# For this example we read it directly from the response (dev only).
CODE=$(echo $REGISTER | jq -r '.saveUser.login_code')
echo "Verification code: $CODE"

# ── Step 2: Verify account ────────────────────────────────────────────────────
VERIFY=$(curl -s -X POST http://localhost:3000/api/user/verify-accounts \
  -H "Content-Type: application/json" \
  -d "{\"email\": \"ana@example.com\", \"code\": \"$CODE\"}")

echo "Verify response:"
echo $VERIFY | jq .

# ── Step 3: Login ─────────────────────────────────────────────────────────────
LOGIN=$(curl -s -X POST http://localhost:3000/api/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@example.com", "password": "mypassword"}')

TOKEN=$(echo $LOGIN | jq -r '.token')
echo "JWT token: $TOKEN"

# Use $TOKEN in subsequent requests:
# -H "access-token: $TOKEN"

Store the JWT in a secure location (e.g. an HttpOnly cookie or encrypted local storage). Include it in every protected request as access-token: <jwt>. Tokens expire after 365 days.

Authentication & Users

Teams & Players

Events & Matches

Content

Authentication API — register, login, verify, logout

POST /api/user/register

Request

Example

Response

POST /api/user/verify-accounts

Request

Example

Response

Request

Example

Response

POST /api/user/logout

Request

Example

Response

Password Recovery

POST /api/user/recovery-pass

Request

Example

Response

POST /api/user/update-password

Request

Example

Response

Build docs developers (and LLMs) love

Authentication & Users

Teams & Players

Events & Matches

Content

Documentation Index

​POST /api/user/register

​Request

​Example

​Response

​POST /api/user/verify-accounts

​Request

​Example

​Response

​POST /api/user/login

​Request

​Example

​Response

​POST /api/user/logout

​Request

​Example

​Response

​Password Recovery

​POST /api/user/recovery-pass

​Request

​Example

​Response

​POST /api/user/update-password

​Request

​Example

​Response

​End-to-End Example: Register → Verify → Login

Build docs developers (and LLMs) love

POST /api/user/register

Request

Example

Response

POST /api/user/verify-accounts

Request

Example

Response

POST /api/user/login

Request

Example

Response

POST /api/user/logout

Request

Example

Response

Password Recovery

POST /api/user/recovery-pass

Request

Example

Response

POST /api/user/update-password

Request

Example

Response

End-to-End Example: Register → Verify → Login