Manage portal users: list, fetch, toggle, and delete

The user-management endpoints allow administrative roles to inspect and control portal user accounts. Every query and mutation is automatically scoped to the caller’s companyId and role as read from the JWT claims, so cross-company access is prevented at the repository layer. The GET /api/auth/me endpoint lets any authenticated user inspect their own identity claims without exposing user-management capabilities.

GET /api/auth/users — List portal users

Method	URL
`GET`	`/api/auth/users`
`GET`	`/api/v1/auth/users`

Authentication: Bearer token required. Allowed roles: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, GESTOR. Returns a paginated-style list of portal users visible to the caller. The database layer filters results by the caller’s CompanyID and enforces the role hierarchy, so a GESTOR only sees users they are permitted to manage.

Query parameters

string

Free-text search term matched against username, email, first name, and last name.

role

string

Filter by exact role name. Valid values: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, GESTOR, CUSTOMER.

onlyActive

boolean

When true, returns only users with IsActive = true. When false, returns only inactive users. Omit to return all users regardless of status.

Response fields

data

array

Array of user objects. See fields below.

totalRows

integer

Total count of users returned (equals data.length).

Each user object in data contains:

userID

integer

Numeric user ID.

companyID

integer

Company the user belongs to.

companyName

string

Name of the company.

username

string

firstName

string

First name.

lastName

string

Last name.

string

Email address.

phone

string

E.164 normalised phone number.

role

string

Role name assigned to the user.

isActive

boolean

Whether the user can currently log in.

mustChangePassword

boolean

Whether the user is required to change their password on next login.

createdAt

string (ISO 8601)

UTC creation timestamp.

updatedAt

string (ISO 8601) | null

UTC last-update timestamp, or null if never updated.

Example request

curl -G https://localhost:7177/api/auth/users \
  -H 'Authorization: Bearer <token>' \
  --data-urlencode 'search=carlos' \
  --data-urlencode 'role=GESTOR' \
  --data-urlencode 'onlyActive=true'

Example response

{
  "data": [
    {
      "userID": 42,
      "companyID": 1,
      "companyName": "ServiciosYa",
      "username": "gestor.norte",
      "firstName": "Carlos",
      "lastName": "Rodríguez",
      "email": "gestor.norte@serviciosya.com",
      "phone": "+595981000001",
      "role": "GESTOR",
      "isActive": true,
      "mustChangePassword": false,
      "createdAt": "2026-04-28T14:30:00Z",
      "updatedAt": null
    }
  ],
  "totalRows": 1
}

GET /api/auth/users/ — Fetch a single user

Method	URL
`GET`	`/api/auth/users/{id}`
`GET`	`/api/v1/auth/users/{id}`

Authentication: Bearer token required. Allowed roles: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, GESTOR. Returns the full PortalUserDto for a single user. Returns 404 if the user does not exist or is outside the caller’s company/role scope — the response is intentionally ambiguous to prevent user enumeration across companies.

Path parameters

integer

required

Numeric ID of the user to fetch.

Example request

curl https://localhost:7177/api/auth/users/42 \
  -H 'Authorization: Bearer <token>'

Example response

{
  "userID": 42,
  "companyID": 1,
  "companyName": "ServiciosYa",
  "username": "gestor.norte",
  "firstName": "Carlos",
  "lastName": "Rodríguez",
  "email": "gestor.norte@serviciosya.com",
  "phone": "+595981000001",
  "role": "GESTOR",
  "isActive": true,
  "mustChangePassword": false,
  "createdAt": "2026-04-28T14:30:00Z",
  "updatedAt": "2026-04-29T09:00:00Z"
}

Error responses

HTTP status	Body	Cause
`404 Not Found`	—	User not found or outside the caller’s visible scope

PATCH /api/auth/users//toggle — Toggle active status

Method	URL
`PATCH`	`/api/auth/users/{id}/toggle`
`PATCH`	`/api/v1/auth/users/{id}/toggle`

Authentication: Bearer token required. Allowed roles: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, GESTOR. Flips the IsActive flag of the specified user. If the user is currently active, they become inactive (and cannot log in); if inactive, they become active again. No request body is required.

Path parameters

integer

required

Numeric ID of the user to toggle.

Response

Returns 204 No Content on success with an empty body.

Example request

curl -X PATCH https://localhost:7177/api/auth/users/42/toggle \
  -H 'Authorization: Bearer <token>'

This endpoint writes an audit event with Action = "TOGGLE_USER_STATUS" scoped to the caller’s identity and IP address.

DELETE /api/auth/users/ — Delete a portal user

Method	URL
`DELETE`	`/api/auth/users/{id}`
`DELETE`	`/api/v1/auth/users/{id}`

Authentication: Bearer token required. Allowed roles: SUPER_ADMIN only. Performs a logical deletion: the user’s account is deactivated and their access is revoked. No data is physically removed from the database. If the user has pending service requests (requests that have not yet reached a terminal state), the deletion is deferred: the user is immediately deactivated but flagged as pendingDeletion = true. The account will be fully cleaned up once all associated service requests are closed. An audit event with Action = "DELETE_PORTAL_USER" is written on every call.

Path parameters

integer

required

Numeric ID of the user to delete.

Response fields

pendingDeletion

boolean

false — the user was deactivated immediately with no outstanding requests.
true — the user was deactivated but has pending service requests; full deletion is deferred.

message

string

Human-readable description of the outcome, in Spanish.

Example request

curl -X DELETE https://localhost:7177/api/auth/users/42 \
  -H 'Authorization: Bearer <token>'

Example response — immediate deletion

{
  "pendingDeletion": false,
  "message": "El usuario quedó inactivo y sin acceso."
}

Example response — deferred deletion

{
  "pendingDeletion": true,
  "message": "El usuario quedó inactivo y pendiente de eliminación hasta cerrar sus trámites."
}

Error responses

HTTP status	Body	Cause
`401 Unauthorized`	—	Missing or invalid token
`403 Forbidden`	—	Caller is not `SUPER_ADMIN`

Deletion is logical and permanent from the user’s perspective — their IsActive is set to false and a deletion record is created. There is no restore endpoint. Use the toggle endpoint if you only need to temporarily suspend an account.

GET /api/auth/companies — List active companies

Method	URL
`GET`	`/api/auth/companies`
`GET`	`/api/v1/auth/companies`

Authentication: Bearer token required. Allowed roles: SUPER_ADMIN only. Returns all active companies registered in the platform. Useful when creating internal users via POST /api/auth/register/internal and a SUPER_ADMIN needs to pick a target company.

Response fields

Each item in the returned array contains:

companyID

integer

Numeric company identifier.

companyName

string

Display name of the company.

Example request

curl https://localhost:7177/api/auth/companies \
  -H 'Authorization: Bearer <token>'

Example response

[
  { "companyID": 1, "companyName": "ServiciosYa" },
  { "companyID": 2, "companyName": "Empresa Demo S.A." }
]

GET /api/auth/me — Current user identity

Method	URL
`GET`	`/api/auth/me`
`GET`	`/api/v1/auth/me`

Authentication: Bearer token required. Any authenticated role. Returns the identity claims extracted directly from the caller’s JWT token. This endpoint performs no database query and is useful for client-side verification that a token is valid and to retrieve the caller’s own IDs without querying the full user list.

Response fields

userId

integer

Numeric ID of the authenticated user.

companyId

integer

Numeric ID of the user’s company.

role

string

Role name from the JWT claim (e.g. "CUSTOMER", "GESTOR", "SUPER_ADMIN").

Example request

curl https://localhost:7177/api/auth/me \
  -H 'Authorization: Bearer <token>'

Example response

{
  "userId": 7,
  "companyId": 1,
  "role": "CUSTOMER"
}

Authentication

Services

Service Requests

System

Manage portal users: list, fetch, toggle, and delete

GET /api/auth/users — List portal users

Query parameters

Response fields

Example request

Example response

GET /api/auth/users/ — Fetch a single user

Path parameters

Example request

Example response

Error responses

PATCH /api/auth/users//toggle — Toggle active status

Path parameters

Response

Example request

DELETE /api/auth/users/ — Delete a portal user

Path parameters

Response fields

Example request

Example response — immediate deletion

Example response — deferred deletion

Error responses

GET /api/auth/companies — List active companies

Response fields

Example request

Example response

GET /api/auth/me — Current user identity

Response fields

Example request

Example response

Build docs developers (and LLMs) love

Authentication

Services

Service Requests

System

Documentation Index

​GET /api/auth/users — List portal users

​Query parameters

​Response fields

​Example request

​Example response

​GET /api/auth/users/ — Fetch a single user

​Path parameters

​Example request

​Example response

​Error responses

​PATCH /api/auth/users//toggle — Toggle active status

​Path parameters

​Response

​Example request

​DELETE /api/auth/users/ — Delete a portal user

​Path parameters

​Response fields

​Example request

​Example response — immediate deletion

​Example response — deferred deletion

​Error responses

​GET /api/auth/companies — List active companies

​Response fields

​Example request

​Example response

​GET /api/auth/me — Current user identity

​Response fields

​Example request

​Example response

Build docs developers (and LLMs) love

GET /api/auth/users — List portal users

Query parameters

Response fields

Example request

Example response

GET /api/auth/users/ — Fetch a single user

Path parameters

Example request

Example response

Error responses

PATCH /api/auth/users//toggle — Toggle active status

Path parameters

Response

Example request

DELETE /api/auth/users/ — Delete a portal user

Path parameters

Response fields

Example request

Example response — immediate deletion

Example response — deferred deletion

Error responses

GET /api/auth/companies — List active companies

Response fields

Example request

Example response

GET /api/auth/me — Current user identity

Response fields

Example request

Example response