Users API — profile, roles, and account management

The Users API provides all post-authentication operations for Gestor Deportivo accounts: editing profile details and avatars, changing passwords while logged in, assigning roles, updating membership and club data, deleting accounts, and listing or searching users. Admin-only operations are clearly marked.

Most endpoints on this page require a valid JWT in the access-token request header. Obtain a token by calling POST /api/user/login. The header format is:

access-token: <jwt_token>

Do not use Authorization: Bearer.

User Object Reference

The shape below represents the user object returned from POST /api/user/login and embedded in various responses across the API.

string

MongoDB ObjectId string uniquely identifying the user.

firstName

string

User’s first name.

lastName

string

User’s last name.

string

Email address (stored lowercase).

avatar

array

Array of image URL strings. Empty array when no avatar has been uploaded.

sex

string

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

idTeam

array

Array of team ObjectId strings that the user belongs to.

idPlayer

string

Associated Player document ID. Empty string when not linked to a player record.

roles

array

Array of role objects { name: string, value: string }. See the Roles table below.

activate

array

Activation state array { name: string, value: string }. An active account contains { name: "1", value: "Activo" }.

membership

string

Current membership tier. One of "Plan Gratis", "Plan Basico", or "Plan Premium". Default: "Plan Gratis".

academyOrClub

string

Affiliation type. One of "Sin academia o club", "Academia", or "Club". Default: "Sin academia o club".

Roles

`value`	`name`	Description
`"1"`	`"Usuario"`	Standard user. Default role assigned at registration.
`"2"`	`"Admin"`	Administrator. Can manage roles, membership data, and view all users.

POST /api/user/update-user/:userId

Update a user’s first name, last name, and/or avatar image. Only the account owner can edit their own profile. The request must be sent as multipart/form-data because of the optional file upload.

Requires access-token header. Only the owner of the account (userId) may call this endpoint.

Request

Headers

Header	Value
`access-token`	Valid JWT

Path parameters

userId

string

required

The MongoDB ObjectId of the user to update.

Body fields

firstName

string

New first name.

lastName

string

New last name.

File upload (optional)

avatar

file

New profile image. Replaces the existing avatar when supplied.

Example

curl -X POST http://localhost:3000/api/user/update-user/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "firstName=Carlos" \
  -F "lastName=Ramírez" \
  -F "avatar=@/path/to/new-photo.jpg"

Response

200 — Updated

{
  "message": "Usuario actualiado correctamente",
  "status": true,
  "data": { "acknowledged": true, "modifiedCount": 1, "matchedCount": 1 },
  "userUpdate": {
    "firstName": "Carlos",
    "lastName": "Ramírez",
    "avatar": ["https://storage.example.com/OauthUser/37new-photo.jpg"]
  }
}

status

boolean

true on success.

data

object

MongoDB updateOne result object including modifiedCount and matchedCount.

userUpdate

object

The fields that were written (firstName, lastName, avatar).

Error responses

HTTP status	Condition
`403`	The requester’s `userId` does not match the document’s `_id` (not the owner).
`404`	No user found for the given `userId`.

POST /api/user/update-password/:userId/token

Change a password while already authenticated. Unlike the code-based recovery flow, this endpoint validates identity via the access-token header and requires both newPassword and confirmNewPassword to be provided.

Requires access-token header.

Note: the source controller returns status: false in the success response body — this is the behaviour as implemented in the current codebase.

Request

Headers

Header	Value
`access-token`	Valid JWT

Path parameters

userId

string

required

The MongoDB ObjectId of the user changing their password.

Body fields

string

required

Must match the email address stored on the user document.

newPassword

string

required

The new password.

confirmNewPassword

string

required

Confirmation of the new password. Must match newPassword.

Example

curl -X POST http://localhost:3000/api/user/update-password/64f1a2b3c4d5e6f7a8b9c0d1/token \
  -H "Content-Type: application/json" \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "email": "carlos@example.com",
    "newPassword": "newSecurePass1!",
    "confirmNewPassword": "newSecurePass1!"
  }'

Response

200 — Updated

{
  "message": "Contraseña actualizada correctamente",
  "status": false
}

message

string

Confirmation message.

status

boolean

Returns false as implemented in the current source.

Error responses

HTTP status	Condition
`403`	The calling user’s ID does not match `userId`, or the supplied email does not match the stored email.
`404`	No user found for the given `userId`.

POST /api/user/update-roles/:userId

Replace the roles array of a target user. The caller must be an admin ({ name: "Admin", value: "2" }) and must pass their own user ID in adminId for server-side validation.

Only users with the Admin role (value: "2") may call this endpoint. Attempting to call it as a standard user returns a 403. Changes to the roles array take effect immediately and affect all subsequent token-protected requests made by the target user.

Request

Headers

Header	Value
`access-token`	Valid JWT (admin)

Path parameters

userId

string

required

The MongoDB ObjectId of the user whose roles will be updated.

Body fields

roles

array

required

The complete new roles array. Each element must be an object with name (string) and value (string). Example: [{ "name": "Admin", "value": "2" }].

adminId

string

required

The MongoDB ObjectId of the admin performing the operation. The server looks up this ID and verifies the admin role before applying any changes.

Example

curl -X POST http://localhost:3000/api/user/update-roles/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Content-Type: application/json" \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "roles": [
      { "name": "Usuario", "value": "1" },
      { "name": "Admin", "value": "2" }
    ],
    "adminId": "64a0b1c2d3e4f5a6b7c8d9e0"
  }'

Response

200 — Roles updated

{
  "message": "Permisos del usuario actualizado correctamente",
  "status": true,
  "updatingRoles": {
    "acknowledged": true,
    "modifiedCount": 1,
    "matchedCount": 1
  }
}

status

boolean

true on success.

updatingRoles

object

MongoDB updateOne result with modifiedCount and matchedCount.

Error responses

HTTP status	Condition
`403`	The `adminId` was not found, the caller does not have the Admin role, or the target `userId` was not found.

POST /api/user/update-data/:userId

Update a user’s membership tier and academy/club affiliation. Admin-only operation.

Requires access-token header. Caller must be an Admin.

Request

Headers

Header	Value
`access-token`	Valid JWT (admin)

Path parameters

userId

string

required

The MongoDB ObjectId of the user to update.

Body fields

membership

string

required

New membership plan. Must be one of:

"Plan Gratis"
"Plan Basico"
"Plan Premium"

academyOrClub

string

required

New affiliation type. Must be one of:

"Sin academia o club"
"Academia"
"Club"

adminId

string

required

The MongoDB ObjectId of the admin performing the operation. Validated server-side.

Example

curl -X POST http://localhost:3000/api/user/update-data/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Content-Type: application/json" \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "membership": "Plan Premium",
    "academyOrClub": "Club",
    "adminId": "64a0b1c2d3e4f5a6b7c8d9e0"
  }'

Response

200 — Updated

{
  "message": "Permisos del usuario actualizado correctamente",
  "status": true
}

status

boolean

true on success.

Error responses

HTTP status	Condition
`403`	`adminId` not found, caller lacks Admin role, or target `userId` not found.

POST /api/user/delete/:userId

Permanently delete a user account. Only the account owner can delete their own account.

Requires access-token header.

This action is irreversible. The user document is hard-deleted from MongoDB via findByIdAndDelete. There is no soft-delete or recovery path.

Request

Headers

Header	Value
`access-token`	Valid JWT

Path parameters

userId

string

required

The MongoDB ObjectId of the account to delete.

Example

curl -X POST http://localhost:3000/api/user/delete/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

200 — Deleted

{
  "message": "Usuario eliminado correctamente",
  "status": true
}

status

boolean

true on success.

Error responses

HTTP status	Condition
`403`	The `userId` in the path does not match the found document’s `_id`.

POST /api/user/list-user/:adminId/:pag?/:perpage?

Retrieve a paginated list of all users in the system. Each record includes only the safe subset of fields: _id, firstName, lastName, email, avatar, roles, and activate.

This is an admin-only endpoint. The adminId path parameter is validated server-side; the request is rejected if the referenced user does not hold the Admin role.

Request

Headers

Header	Value
`access-token`	Valid JWT (admin)

Path parameters

adminId

string

required

The MongoDB ObjectId of the calling admin. Used for role verification.

pag

number

Page number (1-based). Defaults to 1 when omitted.

perpage

number

Records per page. Defaults to 10 when omitted.

Example

# Page 2, 20 records per page
curl -X POST http://localhost:3000/api/user/list-user/64a0b1c2d3e4f5a6b7c8d9e0/2/20 \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

200 — OK

{
  "message": "Mostrando todos los usuarios",
  "status": true,
  "data": [
    {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "firstName": "Carlos",
      "lastName": "Gómez",
      "email": "carlos@example.com",
      "avatar": ["https://storage.example.com/OauthUser/12photo.jpg"],
      "roles": [{ "name": "Usuario", "value": "1" }],
      "activate": [{ "name": "1", "value": "Activo" }]
    }
  ],
  "pagination": {
    "pag": "2",
    "perpage": 20,
    "pags": 5
  }
}

data

array

Array of user objects. Each object contains _id, firstName, lastName, email, avatar, roles, and activate.

pagination

object

Pagination metadata.

Show pagination fields

pagination.pag

string

Current page number (as passed in the URL).

pagination.perpage

number

Number of records per page.

pagination.pags

number

Total number of pages, calculated as Math.ceil(totalCount / perpage).

Error responses

HTTP status	Condition
`403`	The `adminId` was not found or does not have the Admin role.

POST /api/user/search/:query/:pag?/:perpage?

Search users by first name using a case-insensitive regular expression. Results are paginated identically to list-user. Sorted newest-first by _id.

This is an admin-only endpoint. The calling user’s roles are read from the decoded JWT (req.user.roles). The request is silently ignored (no response sent) if the caller is not an admin.

Request

Headers

Header	Value
`access-token`	Valid JWT (admin)

Path parameters

query

string

required

Search string. Matched case-insensitively against firstName. For example, carlos matches Carlos, CARLOS, carlOS, etc.

pag

number

Page number (1-based). Defaults to 1 when omitted.

perpage

number

Records per page. Defaults to 10 when omitted.

Example

# Search for users whose firstName contains "ana", page 1, 10 per page
curl -X POST http://localhost:3000/api/user/search/ana/1/10 \
  -H "access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

200 — Results

{
  "message": "Cargando...",
  "status": true,
  "data": [
    {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d2",
      "firstName": "Ana",
      "lastName": "Torres",
      "email": "ana@example.com",
      "avatar": [],
      "roles": [{ "name": "Usuario", "value": "1" }],
      "activate": [{ "name": "1", "value": "Activo" }]
    }
  ],
  "pagination": {
    "pag": "1",
    "perpage": 10,
    "pags": 1
  }
}

data

array

Array of matching user objects, sorted by _id descending (newest first).

pagination

object

Same pagination structure as list-user: pag, perpage, and pags.

Error conditions

Condition	Behaviour
Caller is not an Admin	No response is sent (connection hangs). Ensure valid admin token.
Query matches zero documents	Returns `data: []` with `pags: 0`.

Authentication & Users

Teams & Players

Events & Matches

Content

Users API — profile, roles, and account management

User Object Reference

Roles

POST /api/user/update-user/:userId

Request

Example

Response

POST /api/user/update-password/:userId/token

Request

Example

Response

POST /api/user/update-roles/:userId

Request

Example

Response

POST /api/user/update-data/:userId

Request

Example

Response

POST /api/user/delete/:userId

Request

Example

Response

POST /api/user/list-user/:adminId/:pag?/:perpage?

Request

Example

Response

POST /api/user/search/:query/:pag?/:perpage?

Request

Example

Response

Build docs developers (and LLMs) love

Authentication & Users

Teams & Players

Events & Matches

Content

Documentation Index

​User Object Reference

​Roles

​POST /api/user/update-user/:userId

​Request

​Example

​Response

​POST /api/user/update-password/:userId/token

​Request

​Example

​Response

​POST /api/user/update-roles/:userId

​Request

​Example

​Response

​POST /api/user/update-data/:userId

​Request

​Example

​Response

​POST /api/user/delete/:userId

​Request

​Example

​Response

​POST /api/user/list-user/:adminId/:pag?/:perpage?

​Request

​Example

​Response

​POST /api/user/search/:query/:pag?/:perpage?

​Request

​Example

​Response

Build docs developers (and LLMs) love

User Object Reference

Roles

POST /api/user/update-user/:userId

Request

Example

Response

POST /api/user/update-password/:userId/token

Request

Example

Response

POST /api/user/update-roles/:userId

Request

Example

Response

POST /api/user/update-data/:userId

Request

Example

Response

POST /api/user/delete/:userId

Request

Example

Response

POST /api/user/list-user/:adminId/:pag?/:perpage?

Request

Example

Response

POST /api/user/search/:query/:pag?/:perpage?

Request

Example

Response