Users API — Account Management and Auth Endpoints

The Users API handles every aspect of identity in StockManager: session-based authentication, account registration with admin approval, full CRUD for the user roster, a three-step password recovery flow, vendor autocomplete for sale forms, and self-service profile settings. Most mutating operations require the admin or root role. Passwords are stored as Werkzeug pbkdf2:sha256 hashes and are never returned in any response. The three valid roles are admin, vendedor, and root.

Authentication

Authenticates a user and creates a server-side session. Accepts either a username or e-mail address in the username field.

username

string

required

Username or e-mail address of the account.

password

string

required

Plain-text password (transmitted over HTTPS, compared against stored hash).

Responses

success

boolean

Always true on a 200 response.

user_id

integer

Primary key of the authenticated user.

username

string

Display name stored in the database.

role

string

One of admin, vendedor, or root.

Status	Meaning
`200`	Login successful; session cookie set.
`400`	`username` or `password` field is empty.
`401`	Credentials do not match any account.
`403`	Account is disabled (`status = 0`) or role is not recognized.

curl -X POST http://localhost:5000/api/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"username": "jdoe", "password": "s3cret"}'

{
  "success": true,
  "user_id": 7,
  "username": "jdoe",
  "role": "admin"
}

POST /api/register

Creates a new account with status = 0 (inactive) and application = "pending". The account cannot log in until an administrator approves it by setting status = 1. New accounts are always assigned the vendedor role.

username

string

required

Desired username. Maximum 30 characters.

string

required

Valid e-mail address. Maximum 100 characters.

password

string

required

Minimum 6 characters.

Responses

success

boolean

true on successful registration.

message

string

Human-readable confirmation, e.g. "Cuenta creada. Espera la aprobación del administrador.".

Status	Meaning
`201`	Account created and pending approval.
`400`	Missing fields, invalid e-mail, or password shorter than 6 characters.
`409`	Username or e-mail already exists.

Registered accounts are inactive until an admin changes their status to 1 via PUT /api/users/:id.

User Management

All endpoints in this section require the admin or root role.

GET /api/users

Returns a paginated, searchable list of all users.

string

Filters by username or e-mail (case-insensitive LIKE match). Omit to return all users.

page

integer

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

limit

integer

Records per page. Defaults to 10; maximum 100.

Response

data

array

Array of user objects for the current page.

Show User object fields

integer

Row ID.

username

string

Display name.

string

E-mail address.

role

string

admin, vendedor, or root.

status

integer

1 = active, 0 = inactive.

created_at

string

ISO-8601 timestamp.

total

integer

Total number of matching records across all pages.

page

integer

Current page number.

pages

integer

Total number of pages.

limit

integer

Page size used for this response.

curl -b cookies.txt \
  "http://localhost:5000/api/users?search=maria&page=1&limit=20"

GET /api/users/:id

Returns a single user by their primary key.

Status	Meaning
`200`	User found.
`404`	No user with that ID exists.

Response — same fields as the objects inside the data array above.

curl -b cookies.txt http://localhost:5000/api/users/7

POST /api/users

Creates a new user directly without the registration approval flow. The new account is immediately active (status = 1).

username

string

required

Display name for the account.

string

required

Must be a valid e-mail and unique in the database.

password

string

required

Plain-text password; stored as a hash.

role

string

required

One of admin, vendedor, or root.

Status	Meaning
`201`	`{"message": "Usuario creado exitosamente"}`
`400`	Missing required fields or invalid e-mail format.
`409`	E-mail or username already registered.

curl -X POST http://localhost:5000/api/users \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username": "jane", "email": "jane@example.com", "password": "pass123", "role": "vendedor"}'

PUT /api/users/:id

Partially updates a user. Only fields present in the request body are evaluated; fields whose values are unchanged are silently ignored — no unnecessary writes occur. On success, a notification is automatically sent to the affected user.

username

string

New display name.

string

New e-mail address; must be unique.

role

string

New role: admin, vendedor, or root.

status

integer

1 to activate, 0 to deactivate.

password

string

If provided (and non-empty), the password is re-hashed and updated.

Status	Meaning
`200`	Update applied (or no changes detected).
`404`	User not found.
`409`	New e-mail is already taken by another account.

DELETE /api/users/:id

Performs a soft delete — sets status = 0 rather than removing the row. The operation is refused when id matches the currently authenticated user.

Status	Meaning
`200`	`{"message": "Usuario dado de baja"}`
`400`	Attempted to deactivate your own account.

This is a logical deletion only. The user record remains in the database and can be reactivated via PUT /api/users/:id with {"status": 1}.

Password Reset Flow

All three steps below are unauthenticated — they are designed to be called from the public-facing login screen. The reset code is a cryptographically random 6-digit string valid for 15 minutes.

Request a reset code

POST /api/users/reset-password

string

required

Registered e-mail address of the account to recover.

Returns 200 {"message": "Codigo enviado al correo"} on success, 404 if the e-mail is not registered.

curl -X POST http://localhost:5000/api/users/reset-password \
  -H "Content-Type: application/json" \
  -d '{"email": "jdoe@example.com"}'

Validate the code

POST /api/users/validate-code

string

required

Same e-mail used in step 1.

code

string

required

The 6-digit code received by e-mail.

Returns 200 if the code is valid, 401 if it has expired or does not match.

curl -X POST http://localhost:5000/api/users/validate-code \
  -H "Content-Type: application/json" \
  -d '{"email": "jdoe@example.com", "code": "482916"}'

Set a new password

POST /api/users/reset-password/change-passwordThe server re-validates the code before applying the change. The code is deleted from the database immediately after a successful reset to prevent reuse.

string

required

Account e-mail address.

code

string

required

The same 6-digit code from step 1.

new_password

string

required

The desired new password.

Returns 200 {"message": "Contraseña restablecida exitosamente"} on success, 401 if the code is expired or invalid.

curl -X POST http://localhost:5000/api/users/reset-password/change-password \
  -H "Content-Type: application/json" \
  -d '{"email": "jdoe@example.com", "code": "482916", "new_password": "newS3cret!"}'

Vendor Autocomplete

GET /api/suggest/vendors

Returns up to 10 active users with the vendedor or admin role whose username or e-mail matches the search string. Used to populate vendor picker inputs when creating a sale. Auth: any authenticated session.

string

required

Search string matched against both username and email with a LIKE query. Returns an empty array when q is blank.

Response

data

array

Matched user suggestions (maximum 10).

Show Suggestion object

integer

User ID.

username

string

Display name.

string

E-mail address.

curl -b cookies.txt "http://localhost:5000/api/suggest/vendors?q=carlos"

{
  "data": [
    {"id": 3, "username": "carlos_v", "email": "carlos@example.com"},
    {"id": 11, "username": "carlos_admin", "email": "cadmin@example.com"}
  ]
}

Profile Settings

Both endpoints below operate on the currently authenticated user’s own account — no admin role is required.

PUT /api/api/settings/profile

Updates the authenticated user’s e-mail address.

string

required

New e-mail address. Must contain @ and ..

Response

success

boolean

true on a successful update.

message

string

Confirmation string, e.g. "Perfil actualizado correctamente".

Status	Meaning
`200`	Profile updated.
`400`	`email` is missing or malformed.

curl -X PUT http://localhost:5000/api/api/settings/profile \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"email": "new_address@example.com"}'

PUT /api/api/settings/password

Changes the authenticated user’s password. The current password must be supplied and verified before the new one is stored.

current_password

string

required

The user’s existing password (verified against stored hash).

new_password

string

required

Desired new password. Minimum 6 characters.

confirm_password

string

required

Must match new_password exactly.

Response

success

boolean

true on a successful change.

message

string

Confirmation string, e.g. "Contraseña actualizada correctamente".

Status	Meaning
`200`	Password updated.
`400`	Missing fields, passwords do not match, or new password is shorter than 6 characters.
`401`	`current_password` is incorrect.

curl -X PUT http://localhost:5000/api/api/settings/password \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "oldS3cret",
    "new_password": "newS3cret!",
    "confirm_password": "newS3cret!"
  }'

Overview

Endpoints

Users API — Account Management and Auth Endpoints

Authentication

POST /api/register

User Management

GET /api/users

GET /api/users/:id

POST /api/users

PUT /api/users/:id

DELETE /api/users/:id

Password Reset Flow

Vendor Autocomplete

GET /api/suggest/vendors

Profile Settings

PUT /api/api/settings/profile

PUT /api/api/settings/password

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Authentication

​POST /api/login

​POST /api/register

​User Management

​GET /api/users

​GET /api/users/:id

​POST /api/users

​PUT /api/users/:id

​DELETE /api/users/:id

​Password Reset Flow

​Vendor Autocomplete

​GET /api/suggest/vendors

​Profile Settings

​PUT /api/api/settings/profile

​PUT /api/api/settings/password

Build docs developers (and LLMs) love

Authentication

POST /api/login

POST /api/register

User Management

GET /api/users

GET /api/users/:id

POST /api/users

PUT /api/users/:id

DELETE /api/users/:id

Password Reset Flow

Vendor Autocomplete

GET /api/suggest/vendors

Profile Settings

PUT /api/api/settings/profile

PUT /api/api/settings/password