Users, Roles, and Access Control in Comunidades Vecinos

Every person who interacts with Comunidades Vecinos is represented by a Usuario record tied to one community. Access to features is controlled by a three-tier role system enforced through Spring Security @PreAuthorize annotations on every endpoint. Roles are stored as a Rol enum value in the database and are also embedded in the JWT token so the frontend can gate UI elements without additional API calls.

The Three Roles

USER

A regular resident (vecino). Can view their own receipts and outstanding balance, read community financial movements, download community documents, and read news posts. Can update their own profile and change their own password.

ADMIN

Community manager — typically the president or treasurer. Has all USER capabilities plus: manage community residents, create and delete fees, view all community receipts and the delinquency report, record financial movements, upload and delete documents, and publish news posts.

SUPER_ADMIN

Platform-level administrator. Has full access across all communities: create/update communities, view all users globally, access all movements, and upload documents to any community using the idComunidadManual override.

Capability Matrix

Capability	USER	ADMIN	SUPER_ADMIN
View own receipts (`GET /api/recibos/me`)	✅	✅	—
View community movements	✅	✅	✅
View movements linked to own account	✅	✅	—
Update own profile	✅	✅	✅
Change own password	✅	✅	✅
View community documents	✅	✅	✅
Read news posts	✅	✅	—
Manage community users	—	✅	✅
Create / delete fees	—	✅	✅
View all community receipts	—	✅	—
View delinquency report	—	✅	—
Create financial movements	—	✅	✅
Upload / delete documents	—	✅	✅
Publish / edit / delete news	—	✅	—
Manage all communities	—	—	✅
View all users globally	—	—	✅
View all movements globally	—	—	✅

The Usuario Entity

Field	Column	Type	Description
`id`	`id_usuario`	`Long` (auto)	Primary key
`dni`	`dni`	`String`	National ID number
`nombre`	`nombre`	`String`	First name
`apellidos`	`apellidos`	`String`	Surnames
`puerta`	`puerta`	`String`	Apartment / door identifier
`telefono`	`telefono`	`String`	Phone number
`email`	`email`	`String`	Login username (used as Spring `getUsername()`)
`password`	`password`	`String`	BCrypt-hashed password (`WRITE_ONLY` in JSON)
`rol`	`rol`	`Rol` enum	`USER`, `ADMIN`, or `SUPER_ADMIN`
`comunidad`	`id_comunidad` (FK)	`Comunidad`	The community this user belongs to
`coeficiente`	`coeficiente`	`Double`	Ownership share (%) used for proportional fee calculation
`estado`	`estado`	`Boolean`	`true` = active; `false` = soft-deleted
`cambiarPass`	`cambiar_pass`	`Boolean`	`true` forces a password change on first login

When an ADMIN creates a new user, the account is created with cambiarPass = true. Until the user changes their password, the getAuthorities() method on the Usuario entity returns ROLE_PRE_AUTH instead of the user’s actual role. This special role is blocked by all business-logic endpoints — the user can only call PATCH /api/usuarios/pass to set a new password.

Admin creates the user

The ADMIN calls POST /api/usuarios with the new resident’s details. The backend sets cambiarPass = true and assigns a temporary password.

User receives credentials

The resident receives their temporary password (typically by email) and logs in for the first time, obtaining a JWT with the ROLE_PRE_AUTH authority.

User changes their password

The user submits their old (temporary) password and chosen new password to PATCH /api/usuarios/pass. The request body uses the CambioPass DTO with oldPassword and newPassword fields.

{
  "oldPassword": "temporal123",
  "newPassword": "MiNuevaContraseña!2024"
}

Full access granted

The backend sets cambiarPass = false. On the next login, the JWT is issued with the user’s real role (ROLE_USER, ROLE_ADMIN, etc.) and all features become accessible.

Key API Endpoints

POST /api/usuarios
Authorization: Bearer <admin_token>
Content-Type: application/json

The community is automatically assigned from the JWT — do not include it in the request body. Returns 409 Conflict if a user with the same DNI already exists. The rol field is always set to USER by the service layer regardless of the value provided.

{
  "dni": "12345678A",
  "nombre": "María",
  "apellidos": "García López",
  "puerta": "3B",
  "telefono": "600123456",
  "email": "[email protected]",
  "coeficiente": 8.5
}

GET /api/usuarios/comunidad
Authorization: Bearer <admin_token>

Returns all users in the ADMIN’s own community. The community ID is resolved from the JWT, not from the URL.

[
  {
    "id": 12,
    "dni": "12345678A",
    "nombre": "María",
    "apellidos": "García López",
    "puerta": "3B",
    "email": "[email protected]",
    "rol": "USER",
    "coeficiente": 8.5,
    "estado": true,
    "cambiarPass": false
  }
]

GET /api/usuarios/me
Authorization: Bearer <any_token>

Accessible by all authenticated roles. Returns the profile of the user identified by the JWT’s principal name (email).

PUT /api/usuarios/modificar
Authorization: Bearer <any_token>
Content-Type: application/json

The user ID is resolved from the JWT. Users can update their own nombre, apellidos, telefono, and puerta. Role and community cannot be self-modified.

PUT /api/usuarios/admin/{id}
Authorization: Bearer <admin_token>
Content-Type: application/json

Allows an ADMIN to update any field on another user, including rol, coeficiente, and estado (for reactivating a soft-deleted account).

DELETE /api/usuarios/{idUsuario}
Authorization: Bearer <admin_token>

Sets estado = false on the user record. The database row is retained. Returns 200 OK with a confirmation message or 404 if not found.

Admin Password Reset

An ADMIN can trigger a password reset for any user in their community without knowing the current password:

PATCH /api/usuarios/admin/{id}
Authorization: Bearer <admin_token>

The backend generates a new temporary password, sends it to the user’s registered email address, and sets cambiarPass = true so the user is forced through the first-login flow again on their next session.

The `coeficiente` Field

Each resident’s coeficiente value represents their ownership share of the community as a percentage. This number is used directly by the fee-generation logic: when a new ORDINARIA or EXTRAORDINARIA fee is created, each resident’s receipt amount is calculated as:

importe_recibo = importe_cuota × coeficiente / 100

Users with a null or zero coeficiente are skipped during automatic receipt generation. This typically applies to commercial units or common-area entries that are not billed.

Deleting a user via DELETE /api/usuarios/{idUsuario} does not remove the database record. It performs a soft delete by setting estado = false and resetting coeficiente to 0.0, which prevents them from being included in future receipt generation. Inactive users cannot log in. Their existing receipts, movements, and document references are preserved for financial integrity. To reactivate a user, call PUT /api/usuarios/admin/{id} and restore the appropriate estado and coeficiente values.

Getting Started

Core Features

Configuration

Users, Roles, and Access Control in Comunidades Vecinos

The Three Roles

USER

ADMIN

SUPER_ADMIN

Capability Matrix

The Usuario Entity

Key API Endpoints

Admin Password Reset

The `coeficiente` Field

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Documentation Index

​The Three Roles

USER

ADMIN

SUPER_ADMIN

​Capability Matrix

​The Usuario Entity

​First-Login Password Flow

​Key API Endpoints

​Admin Password Reset

​The coeficiente Field

Build docs developers (and LLMs) love

The Three Roles

Capability Matrix

The Usuario Entity

First-Login Password Flow

Key API Endpoints

Admin Password Reset

The `coeficiente` Field