Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Luisangelebp/SCO_Autolavados/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Users API handles authentication, account creation, profile management, and role-based access control for SCO Autolavados. Three registration paths exist:
  • Online self-registration — customers create their own account via POST /api/users/register.
  • Reception quick-registration — admin staff create walk-in accounts (no email/password required) via POST /api/users/admin.
  • Account activation — a previously reception-created user later activates their account online through POST /api/users/register using the same cedula.

​
Authentication

Protected endpoints require a Bearer JWT token obtained from POST /api/users/login. Access tokens expire in 15 minutes; use the refresh token flow to obtain a new one. 
Authorization: Bearer <your_jwt_token>
Access tokens are valid for 15 minutes. Refresh tokens are valid for 7 days. Use POST /api/users/refresh with { "refreshToken": "..." } to silently obtain a new access token without requiring the user to log in again.

​
User Object

All user endpoints that return a user return this shape. The hashPassword field is always stripped from API responses. 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cedula": "V12345678",
  "name": "Juan",
  "lastName": "Pérez",
  "phone": "04141234567",
  "user": "juanperez",
  "email": "[email protected]",
  "photo": null,
  "status": true,
  "isWorkingToday": false,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "role": { "id": "uuid", "name": "CUSTOMER" }
}
​
id
string
UUID primary key of the user.
​
cedula
string
National ID or tax ID. Must start with V, E, J, or G (e.g. V12345678).
​
name
string
User’s first name.
​
lastName
string
User’s last name.
​
phone
string
Contact phone number (e.g. 04141234567).
​
user
string | null
Unique username. Only set when the account has been activated with email/password.
​
email
string | null
Unique email address. Only set when the account has been activated with email/password.
​
photo
string | null
Stored filename of the uploaded profile photo, or null if none.
​
status
boolean
Whether the account is active. Defaults to true.
​
isWorkingToday
boolean
Only meaningful for LAUNDRER role — true when the employee has an active shift.
​
createdAt
string (ISO 8601)
Timestamp of account creation.
​
role
object
Embedded role object { id, name }.

​
Endpoints

​
POST /api/users/login

Authenticates a user by email or username and returns a JWT access token and a refresh token. 
curl -X POST http://localhost:3000/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "[email protected]",
    "password": "mi_password_seguro"
  }'
Request body:
​
identifier
string
required
The user’s registered email address or username (user field).
​
password
string
required
The user’s plain-text password. Compared against the bcrypt hash stored in the database.
Response 200 OK: 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "role": { "id": "uuid", "name": "CUSTOMER" }
  }
}
​
token
string
Short-lived JWT access token (expires in 15 minutes). Send as Authorization: Bearer <token> on protected requests.
​
refreshToken
string
Long-lived refresh token (expires in 7 days). Use with POST /api/users/refresh to get a new access token.
​
user
object
Partial user object with id, email, and the nested role object.
Error 401 Unauthorized — Invalid credentials or account not yet activated (no password set).

​
GET /api/users ADMIN

Returns a paginated list of all users in the system, ordered by most recently created. Requires a valid JWT from an ADMIN account. 
curl http://localhost:3000/api/users?cant=20&page=1 \
  -H "Authorization: Bearer <admin_token>"
Query parameters:
​
cant
number
Number of records per page. Defaults to 10. Must be a positive integer.
​
page
number
Page number (1-indexed). Defaults to 1.
Response 200 OK: 
{
  "users": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "cedula": "V12345678",
      "name": "Juan",
      "lastName": "Pérez",
      "phone": "04141234567",
      "user": "juanperez",
      "email": "[email protected]",
      "photo": null,
      "status": true,
      "isWorkingToday": false,
      "createdAt": "2026-06-01T10:00:00.000Z",
      "role": { "id": "uuid", "name": "CUSTOMER" }
    }
  ],
  "total": 42
}
​
users
array
Array of User objects (see User Object above).
​
total
number
Total count of all users in the database (useful for building pagination UI).

​
GET /api/users/role/:roleName

Returns all users that belong to a specific role. The lookup is case-insensitive — CUSTOMER, customer, and Customer all match the same role. 
curl http://localhost:3000/api/users/role/CUSTOMER
Path parameters:
​
roleName
string
required
Name of the role to filter by. Built-in system roles are ADMIN, CUSTOMER, and LAUNDRER. The match is case-insensitive.
Response 200 OK: 
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cedula": "V12345678",
    "name": "Juan",
    "lastName": "Pérez",
    "phone": "04141234567",
    "user": "juanperez",
    "email": "[email protected]",
    "photo": null,
    "status": true,
    "isWorkingToday": false,
    "createdAt": "2026-06-01T10:00:00.000Z",
    "role": { "id": "uuid", "name": "CUSTOMER" }
  }
]
Returns an empty array [] if no users match the given role name.

​
GET /api/users/check/:cedula

Checks whether a cedula (national ID) already exists in the database. Designed for the online registration form auto-fill flow: if the user was pre-created at the reception desk, their name and phone number can be pre-populated. 
curl http://localhost:3000/api/users/check/V12345678
Path parameters:
​
cedula
string
required
The cedula or RIF to look up (e.g. V12345678, J123456789).
Response 200 OK — User was found: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cedula": "V12345678",
  "name": "Juan",
  "lastName": "Pérez",
  "phone": "04141234567",
  "user": null,
  "email": null,
  "photo": null,
  "status": true,
  "isWorkingToday": false,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "role": { "id": "uuid", "name": "CUSTOMER" }
}
Response 404 Not Found — Cedula does not exist: 
{ "error": "Usuario no encontrado" }

​
POST /api/users/register

Online self-registration for customers. Supports two flows:
  1. New user — Creates a brand-new CUSTOMER account from scratch.
  2. Account activation — If a user was pre-created at the reception desk (via POST /api/users/admin) and has no email yet, this endpoint activates their account by adding email, username, and a hashed password.
Supports multipart/form-data for optional profile photo upload alongside the JSON fields. 
curl -X POST http://localhost:3000/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "cedula": "V12345678",
    "name": "Juan",
    "lastName": "Pérez",
    "phone": "04141234567",
    "email": "[email protected]",
    "user": "juanperez",
    "password": "mi_password_seguro"
  }'
Request body:
​
cedula
string
required
National ID or RIF. Must start with V, E, J, or G. Used as the unique lookup key to determine new vs. activation flow.
​
name
string
required
User’s first name.
​
lastName
string
required
User’s last name.
​
phone
string
required
Contact phone number.
​
email
string
required
Unique email address.
​
user
string
required
Desired unique username.
​
password
string
required
Plain-text password. Hashed with bcrypt (salt rounds: 10) before storage.
​
photo
file
Optional profile photo. Send as multipart/form-data. The stored filename is saved to the photo field.
Response 201 Created: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cedula": "V12345678",
  "name": "Juan",
  "lastName": "Pérez",
  "phone": "04141234567",
  "user": "juanperez",
  "email": "[email protected]",
  "photo": null,
  "status": true,
  "isWorkingToday": false,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "role": { "id": "uuid", "name": "CUSTOMER" }
}
If the cedula already has an email associated (i.e. the account is already fully active), the request will fail with a 500 error: "El usuario ya se encuentra registrado y activo con un correo electrónico".

​
POST /api/users/admin ADMIN

Quick-registration flow for walk-in customers or new staff at the physical reception desk. Does not require email or password — the account can be activated later by the user via POST /api/users/register. 
curl -X POST http://localhost:3000/api/users/admin \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan",
    "lastName": "Pérez",
    "roleId": "uuid-del-rol",
    "cedula": "V12345678",
    "phone": "04141234567"
  }'
Request body:
​
name
string
required
User’s first name.
​
lastName
string
required
User’s last name.
​
roleId
string
required
UUID of the role to assign. Obtain valid role UUIDs from GET /api/roles.
​
cedula
string
required
National ID or RIF. Must start with V, E, J, or G.
​
phone
string
required
Contact phone number.
​
email
string
Optional email address if already known at registration time.
​
user
string
Optional username.
​
password
string
Optional plain-text password (will be hashed). Usually omitted in the quick-registration flow.
Response 201 Created: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cedula": "V12345678",
  "name": "Juan",
  "lastName": "Pérez",
  "phone": "04141234567",
  "user": null,
  "email": null,
  "photo": null,
  "status": true,
  "isWorkingToday": false,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "roleId": "uuid-del-rol"
}
The response from POST /api/users/admin does not include the expanded role object — only the raw roleId. Use GET /api/users/role/:roleName or GET /api/users to retrieve users with their role details.

​
PATCH /api/users/:id ADMIN or same user

Updates one or more fields of an existing user account. An ADMIN can update any user; a CUSTOMER can only update their own profile (enforced server-side by comparing the JWT id claim against the path :id). Supports both application/json and multipart/form-data (required when uploading a photo). 
# Update name only (JSON)
curl -X PATCH http://localhost:3000/api/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Juan Carlos" }'

# Upload a new profile photo (multipart)
curl -X PATCH http://localhost:3000/api/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>" \
  -F "name=Juan Carlos" \
  -F "photo=@/path/to/photo.jpg"
Path parameters:
​
id
string
required
UUID of the user to update.
Request body (all fields optional — send only those you want to change):
​
name
string
New first name.
​
lastName
string
New last name.
​
phone
string
New phone number.
​
email
string
New unique email address.
​
user
string
New unique username.
​
password
string
New plain-text password. Will be hashed with bcrypt before storage.
​
photo
file
New profile photo file (multipart only).
​
status
boolean
Account active/inactive flag. ADMIN only in practice.
​
roleId
string
UUID of the new role to assign. ADMIN only in practice.
Response 200 OK: Updated User object (see User Object above). Error 403 Forbidden — A non-admin user attempts to edit another user’s profile: 
{ "error": "No tienes permiso para editar a este usuario" }

​
GET /api/roles

Returns the list of all available roles in the system. No authentication required. 
curl http://localhost:3000/api/roles
Response 200 OK: 
[
  { "id": "uuid-admin", "name": "ADMIN" },
  { "id": "uuid-customer", "name": "CUSTOMER" },
  { "id": "uuid-laundrer", "name": "LAUNDRER" }
]
​
id
string
UUID of the role. Use this value as roleId when creating users via POST /api/users/admin.
​
name
string
Role name. System roles are ADMIN, CUSTOMER, and LAUNDRER.
Call GET /api/roles when building role selector dropdowns in the admin UI. The returned id values are the UUIDs you need for roleId in user creation endpoints.

​
POST /api/users/refresh

Exchanges a valid refresh token for a new short-lived access token, without requiring the user to log in again. 
curl -X POST http://localhost:3000/api/users/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'
Request body:
​
refreshToken
string
required
The refresh token previously received from POST /api/users/login.
Response 200 OK: 
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
Error 401 Unauthorized — Refresh token is missing, expired, or invalid.

Build docs developers (and LLMs) love

Get started for freeTalk to us