Users API — Accounts, Managers, and User Notifications

The Users API covers the full lifecycle of user accounts within UniEvents. Users are always scoped to a tenant (faculty), except for superadmin accounts which operate globally. The service layer hashes all passwords with bcrypt before they reach the database — never store or transmit plain-text passwords. The /managers sub-resource provides tenant-scoped manager management, while /notifications derives real-time alerts from each user’s event attendance records.

GET /api/users

Returns all users that belong to a specific tenant, ordered by creation date (newest first). Authentication: Not required.

tenantId

string

required

UUID of the tenant whose users you want to list. Returns 400 if omitted.

curl "https://your-domain.com/api/users?tenantId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

200 Response

[
  {
    "id": "usr_uuid",
    "email": "maria.garcia@universidad.edu",
    "name": "María",
    "lastName": "García",
    "documentId": "V-12345678",
    "phone": "+58 412 1234567",
    "role": "tenant_admin",
    "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organizerLevel": "academico",
    "createdAt": "2025-03-10T08:00:00.000Z"
  }
]

string

UUID of the user.

string

Unique email address used for login.

name

string | null

First name.

lastName

string | null

Last name / surname.

documentId

string | null

National ID or document number.

phone

string | null

Contact phone number.

role

string

User role. One of superadmin, tenant_admin, event_manager, access_control, or user.

tenantId

string | null

UUID of the user’s tenant. null for superadmin accounts.

organizerLevel

"academico" | "amateur" | "registrado"

Organizer classification. Defaults to "academico".

createdAt

string (ISO 8601)

Timestamp when the account was created.

POST /api/users

Creates a new user account. The passwordHash field accepts a plain-text password — it is hashed with bcrypt (cost 10) before being stored. When creating a tenant_admin, personal identification fields become required. Authentication: Not required. Content-Type: application/json

string

required

Unique email address for the new account.

passwordHash

string

required

Plain-text password. The service hashes this before insertion.

role

string

User role. Defaults to "user" if not provided.

tenantId

string

UUID of the tenant to assign the user to.

name

string

First name. Required when role is "tenant_admin".

lastName

string

Last name. Required when role is "tenant_admin".

documentId

string

National ID or document number. Required when role is "tenant_admin".

phone

string

Contact phone number. Required when role is "tenant_admin".

curl -X POST "https://your-domain.com/api/users" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carlos.mendez@universidad.edu",
    "passwordHash": "SecurePass123!",
    "role": "tenant_admin",
    "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Carlos",
    "lastName": "Méndez",
    "documentId": "V-98765432",
    "phone": "+58 414 9876543"
  }'

201 Response — The created user object (same fields as the GET response above). Error Responses

Status	Description
`400`	`role` is `"tenant_admin"` but `name`, `lastName`, `documentId`, or `phone` is missing.

{
  "error": "Personal information (name, lastName, documentId, phone) is required for tenant administrators."
}

GET /api/users/{id}

Returns a single user by UUID. Authentication: Not required.

string

required

UUID of the user to retrieve.

curl "https://your-domain.com/api/users/usr_uuid"

200 Response — Single user object. 404 if the user does not exist.

PUT /api/users/{id}

Updates an existing user. Only the fields included in the request body are modified. If passwordHash is supplied, it is re-hashed before being stored. Authentication: Not required at the route level (enforce access control in your middleware or client). Content-Type: application/json

string

required

UUID of the user to update.

string

Updated email address.

role

string

Updated role.

tenantId

string | null

Updated tenant assignment. Pass null to unlink.

passwordHash

string

New plain-text password to replace the current one.

curl -X PUT "https://your-domain.com/api/users/usr_uuid" \
  -H "Content-Type: application/json" \
  -d '{"role": "event_manager"}'

200 Response — The updated user object.

DELETE /api/users/{id}

Permanently deletes a user account. Authentication: Not required at the route level.

string

required

UUID of the user to delete.

curl -X DELETE "https://your-domain.com/api/users/usr_uuid"

204 Response — No content. Deletion was successful.

GET /api/users/managers

Returns the list of managers belonging to the current session’s tenant. By default only event_manager role users are returned, but the role query parameter can broaden or narrow the filter. Authentication: Required (session cookie with a valid tenantId). Returns 401 if no session or if the session has no tenantId.

role

string

Filter by role. Defaults to "event_manager" if omitted. Pass any valid role string (e.g. "access_control") to retrieve users with that role instead.

curl "https://your-domain.com/api/users/managers" \
  -H "Cookie: session=<your-session-token>"

# Retrieve access control staff instead
curl "https://your-domain.com/api/users/managers?role=access_control" \
  -H "Cookie: session=<your-session-token>"

200 Response

[
  {
    "id": "usr_uuid",
    "email": "luis.perez@facultad.edu",
    "role": "event_manager",
    "name": "Luis",
    "lastName": "Pérez",
    "documentId": "V-11223344",
    "phone": "+58 416 1122334"
  }
]

string

UUID of the manager.

string

Manager’s email address.

role

string

Role of the user (e.g. "event_manager", "access_control").

name

string | null

First name.

lastName

string | null

Last name.

documentId

string | null

National ID.

phone

string | null

Contact phone.

POST /api/users/managers

Creates a new manager (or access control staff) and automatically scopes them to the current session’s tenant. The tenantId is never accepted from the request body — it is always taken from the authenticated session to prevent tenant spoofing. Authentication: Required. The session user must have the role tenant_admin or superadmin, and must have a tenantId in their session. Returns 401 otherwise. Content-Type: application/json

string

required

Unique email for the new manager account.

passwordHash

string

required

Plain-text password. Hashed with bcrypt (cost 10) before insertion.

role

"event_manager" | "access_control"

Role to assign. Defaults to "event_manager" if an unrecognised value is passed.

name

string

required

First name of the new manager.

lastName

string

required

Last name of the new manager.

documentId

string

required

National ID or document number.

phone

string

required

Contact phone number.

curl -X POST "https://your-domain.com/api/users/managers" \
  -H "Cookie: session=<tenant-admin-session>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana.rivas@facultad.edu",
    "passwordHash": "TempPass456!",
    "role": "event_manager",
    "name": "Ana",
    "lastName": "Rivas",
    "documentId": "V-55667788",
    "phone": "+58 424 5566778"
  }'

201 Response — The newly created manager object. Error Responses

Status	Description
`401`	No session, insufficient role, or session lacks a `tenantId`.

GET /api/users/notifications

Returns a derived list of in-app notifications for the currently authenticated user, based on their event attendance records. No session returns an empty notifications array rather than an error. Authentication: Required (session cookie with a valid userId). Returns { "notifications": [] } if no valid session is found — this endpoint never returns a 401.

curl "https://your-domain.com/api/users/notifications" \
  -H "Cookie: session=<your-session-token>"

200 Response

{
  "notifications": [
    {
      "id": "pending-att_uuid",
      "title": "Pago Pendiente",
      "message": "Tienes un pago pendiente para el evento \"Congreso de Ingeniería 2025\".",
      "type": "warning",
      "link": "/profile",
      "createdAt": "2025-09-01T12:00:00.000Z"
    },
    {
      "id": "verifying-att_uuid",
      "title": "Pago en Verificación",
      "message": "El pago para \"Feria de Ciencias\" está siendo verificado.",
      "type": "info",
      "link": "/profile",
      "createdAt": "2025-09-02T09:30:00.000Z"
    },
    {
      "id": "confirmed-att_uuid",
      "title": "Entrada Confirmada",
      "message": "Tu entrada para \"Workshop de Robótica\" ha sido confirmada.",
      "type": "success",
      "link": "/profile?viewTicket=ticket-uuid",
      "createdAt": "2025-09-03T16:45:00.000Z"
    }
  ]
}

notifications

array

Array of notification objects, sorted by most recent first.

notifications[].id

string

Prefixed identifier derived from the attendance record. Prefix reflects state: pending-, verifying-, or confirmed-.

notifications[].title

string

Short notification title shown in the UI.

notifications[].message

string

Human-readable message describing the notification context, including the event title.

notifications[].type

"warning" | "info" | "success"

Semantic type used to determine badge colour and icon in the UI.

"warning" — payment registered but no reference uploaded yet.
"info" — payment reference uploaded and awaiting admin verification.
"success" — payment verified and ticket confirmed.

notifications[].link

string

Relative URL the user should navigate to for more context. Confirmed tickets include a ?viewTicket= query param with the ticket token.

notifications[].createdAt

string (ISO 8601) | null

Timestamp of the underlying attendance record. For confirmed tickets, this is paymentVerifiedAt if available, otherwise createdAt.

Authentication

Resources

Users API — Accounts, Managers, and User Notifications

GET /api/users

POST /api/users

GET /api/users/{id}

PUT /api/users/{id}

DELETE /api/users/{id}

GET /api/users/managers

POST /api/users/managers

GET /api/users/notifications

Build docs developers (and LLMs) love

Authentication

Resources

Documentation Index

​GET /api/users

​POST /api/users

​GET /api/users/{id}

​PUT /api/users/{id}

​DELETE /api/users/{id}

​GET /api/users/managers

​POST /api/users/managers

​GET /api/users/notifications

Build docs developers (and LLMs) love

GET /api/users

POST /api/users

GET /api/users/{id}

PUT /api/users/{id}

DELETE /api/users/{id}

GET /api/users/managers

POST /api/users/managers

GET /api/users/notifications