User Management Endpoints: Platform User Lifecycle

The /api/users router provides full lifecycle management for platform user accounts. All routes (except the preceptor-accessible /search endpoint) require the authenticated user to hold the admin role — requests from any other role are rejected with 403 Forbidden. Deleting a user is a soft-delete that sets status: inactivo on the profiles table rather than destroying the underlying Supabase Auth record.

GET /api/users

Returns a paginated list of all user profiles. Supports full-text search across nombre, apellido, email, and dni, and can be filtered by role. Auth: requireAuth + requireRole('admin').

Query parameters

string

Case-insensitive substring to match against nombre, apellido, email, or dni.

rol

string

Filter by role. One of admin, docente, estudiante, or preceptor.

page

number

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

limit

number

Number of records per page. Defaults to 20.

Response — `200 OK`

data

array

Array of Profile objects ordered by created_at descending.

Show Profile fields

string

UUID of the profile.

nombre

string

First name.

apellido

string

Last name.

string

Email address.

dni

string | null

National ID number.

celular

string | null

Phone number.

rol

string

Role: admin, docente, estudiante, or preceptor.

status

string

Account status: activo, pendiente, or inactivo.

avatar_url

string | null

Public avatar URL.

ISO 8601 timestamp of last login.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-update timestamp.

total

number

Total number of matching records (for pagination).

page

number

Current page number.

limit

number

Page size used for this response.

Example

curl "https://api.nuestravoz.edu.ar/api/users?rol=docente&page=1&limit=10" \
  --cookie "nuestravoz_session=<admin-token>"

{
  "data": [
    {
      "id": "e3c1a4f0-...",
      "nombre": "Carlos",
      "apellido": "Paredes",
      "email": "cparedes@radio.edu.ar",
      "dni": "29876543",
      "celular": "+54 9 11 9876-5432",
      "rol": "docente",
      "status": "activo",
      "avatar_url": null,
      "last_login": "2025-03-10T09:15:00.000Z",
      "created_at": "2024-08-01T00:00:00.000Z",
      "updated_at": "2025-03-10T09:15:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

GET /api/users/search

Quick search for users by name or DNI, returning a lightweight subset of profile fields. Useful for autocomplete widgets and assignment pickers. Returns up to 30 results. Auth: requireAuth + requireRole('admin', 'preceptor').

Query parameters

string

Search term matched case-insensitively against nombre, apellido, and dni.

Response — `200 OK`

data

array

Show fields per item

string

UUID.

nombre

string

First name.

apellido

string

Last name.

string

Email address.

dni

string | null

National ID.

rol

string

Role.

avatar_url

string | null

Avatar URL.

Example

const res = await fetch(
  "https://api.nuestravoz.edu.ar/api/users/search?q=Giménez",
  { credentials: "include" }
);
const { data } = await res.json();

GET /api/users/stats

Returns aggregate counts for dashboard widgets. Auth: requireAuth + requireRole('admin').

Response — `200 OK`

data

object

Show fields

totalUsuarios

number

Total number of user profiles.

usuariosActivos

number

Number of profiles with status: activo.

totalEstudiantes

number

Number of profiles with rol: estudiante.

Example

curl https://api.nuestravoz.edu.ar/api/users/stats \
  --cookie "nuestravoz_session=<admin-token>"

{
  "data": {
    "totalUsuarios": 342,
    "usuariosActivos": 310,
    "totalEstudiantes": 280
  }
}

POST /api/users

Creates a new platform user. This is the admin path to provision accounts; it bypasses the self-registration flow and always creates the account with status: activo. A Supabase Auth user is created first; if the subsequent profiles insert fails the Auth user is automatically deleted to keep the systems in sync. Auth: requireAuth + requireRole('admin').

Request body

nombre

string

required

First name. Minimum 2 characters.

apellido

string

required

Last name. Minimum 2 characters.

string

required

Email address. Must be unique across the platform.

password

string

required

Initial password. Minimum 6 characters.

rol

string

required

Role to assign. One of admin, docente, estudiante, or preceptor.

dni

string

National ID number. Must be unique if provided.

celular

string

Phone / mobile number.

Response — `201 Created`

data

object

The newly created Profile record.

Error responses

Status	Meaning
`400`	Validation error, duplicate email, or duplicate DNI.
`403`	Caller is not an admin.

Example

const res = await fetch("https://api.nuestravoz.edu.ar/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
  body: JSON.stringify({
    nombre: "Laura",
    apellido: "Méndez",
    email: "lmendez@radio.edu.ar",
    password: "temporal123",
    rol: "preceptor",
    dni: "32100987",
  }),
});
const { data } = await res.json();
console.log(data.id); // UUID of the new profile

PATCH /api/users/:id

Updates any subset of fields on an existing user profile. If password is included it is applied to the Supabase Auth record. If email is included the Supabase Auth identity email is also updated after the profile row is saved. Empty strings for dni and celular are normalised to null. Auth: requireAuth + requireRole('admin').

Path parameters

string

required

UUID of the profile to update.

Request body

All fields are optional. Send only the fields you wish to change.

nombre

string

Updated first name. Minimum 2 characters.

apellido

string

Updated last name. Minimum 2 characters.

string

Updated email. Must be a valid, unique email address.

password

string

New password for the account. Minimum 6 characters.

dni

string

Updated national ID. Must be unique. Pass an empty string to clear.

celular

string

Updated phone number. Pass an empty string to clear.

rol

string

Updated role: admin, docente, estudiante, or preceptor.

status

string

Updated account status: activo, pendiente, or inactivo. Use this to approve a pending docente account.

Response — `200 OK`

data

object

The updated Profile record.

Error responses

Status	Meaning
`400`	Validation error or duplicate DNI.
`403`	Caller is not an admin.

Example

curl -X PATCH https://api.nuestravoz.edu.ar/api/users/e3c1a4f0-1234-5678-abcd-ef0123456789 \
  -H "Content-Type: application/json" \
  --cookie "nuestravoz_session=<admin-token>" \
  -d '{ "status": "activo", "rol": "docente" }'

{
  "data": {
    "id": "e3c1a4f0-1234-5678-abcd-ef0123456789",
    "status": "activo",
    "rol": "docente"
  }
}

DELETE /api/users/:id

Soft-deletes a user by setting their status to inactivo. The underlying Supabase Auth account is not deleted. The user will be blocked from logging in until reactivated via PATCH /api/users/:id. Auth: requireAuth + requireRole('admin').

Path parameters

string

required

UUID of the profile to deactivate.

Response — `200 OK`

data

object

Show fields

message

string

"Usuario desactivado"

Error responses

Status	Meaning
`400`	Database error.
`403`	Caller is not an admin.

Example

const res = await fetch(
  "https://api.nuestravoz.edu.ar/api/users/e3c1a4f0-1234-5678-abcd-ef0123456789",
  { method: "DELETE", credentials: "include" }
);
const { data } = await res.json();
console.log(data.message); // "Usuario desactivado"

Overview

Endpoints

GET /api/users

Query parameters

Response — `200 OK`

Example

GET /api/users/search

Query parameters

Response — `200 OK`

Example

GET /api/users/stats

Response — `200 OK`

Example

POST /api/users

Request body

Response — `201 Created`

Error responses

Example

PATCH /api/users/:id

Path parameters

Request body

Response — `200 OK`

Error responses

Example

DELETE /api/users/:id

Path parameters

Response — `200 OK`

Error responses

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/users

​Query parameters

​Response — 200 OK

​Example

​GET /api/users/search

​Query parameters

​Response — 200 OK

​Example

​GET /api/users/stats

​Response — 200 OK

​Example

​POST /api/users

​Request body

​Response — 201 Created

​Error responses

​Example

​PATCH /api/users/:id

​Path parameters

​Request body

​Response — 200 OK

​Error responses

​Example

​DELETE /api/users/:id

​Path parameters

​Response — 200 OK

​Error responses

​Example

Build docs developers (and LLMs) love

GET /api/users

Query parameters

Response — `200 OK`

Example

GET /api/users/search

Query parameters

Response — `200 OK`

Example

GET /api/users/stats

Response — `200 OK`

Example

POST /api/users

Request body

Response — `201 Created`

Error responses

Example

PATCH /api/users/:id

Path parameters

Request body

Response — `200 OK`

Error responses

Example

DELETE /api/users/:id

Path parameters

Response — `200 OK`

Error responses

Example