Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuillermoNavarro/Proyecto_comunidades/llms.txt

Use this file to discover all available pages before exploring further.

The Comunidades Vecinos API uses JSON Web Tokens (JWT) signed with HMAC-SHA256. Authentication is entirely stateless: the server never stores session data, and every request is authorised solely by verifying the signature and claims embedded in the token. You obtain a token by posting credentials to POST /api/login, then attach that token to all subsequent requests via the Authorization header.

​
Login

​
POST /api/login

Validates the supplied credentials against the database, checks that the account is active, and — if successful — returns a signed JWT as a plain-text string.
This is the only endpoint that does not require a token. All other paths return 401 Unauthorized without a valid Authorization: Bearer <token> header.

​
Request

​
email
string
required
The email address associated with the user’s account.
​
password
string
required
The user’s plain-text password. The backend compares it against a BCrypt hash stored in the database.
curl -X POST http://localhost:8081/api/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "password": "mypassword"}'

​
Responses

​
200 OK
string
A raw JWT string — not JSON-wrapped. Store this value and include it in the Authorization header of every subsequent request.
eyJhbGciOiJIUzI1NiJ9.eyJpZFVzdWFyaW8iOjEsImlkQ29tdW5pZGFkIjoxLCJyb2wiOiJBRE1JTiIsInN1YiI6ImFkbWluQGNvbXVuaWRhZC5jb20iLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.SIGNATURE
​
401 Unauthorized
string
Returned when the credentials are wrong or the account has been deactivated.
Credenciales incorrectas o usuario inactivo.

​
Using the token

Include the token returned by /api/login in every subsequent request using the Authorization header with the Bearer scheme: 
curl http://localhost:8081/api/usuarios/me \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
The backend extracts the token from the header, verifies its signature against the configured secret key, checks the expiry date, and loads the identity from the embedded claims — all without touching the database.

​
JWT claims

Every token issued by the API carries the following claims in its payload:
ClaimTypeDescription
substringThe user’s email address (JWT standard subject).
idUsuariolongThe user’s primary key in the usuarios table.
idComunidadlongThe ID of the community the user belongs to.
rolstringThe user’s role string (see values below).
iattimestampIssued-at time (set automatically).
exptimestampExpiry time — 24 hours after issuance.

​
Role values

rol claim valueDescription
USERRegular resident (vecino).
ADMINCommunity administrator (e.g. president, treasurer).
SUPER_ADMINPlatform manager with access across all communities.
The backend reads idUsuario, idComunidad, and rol directly from the JWT claims on every request. There is no secondary database call to look up the user’s identity during authentication filter processing.

​
First-login password change

Every new user 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 their actual role — regardless of what role the database record holds.
A token issued for a user with cambiarPass = true carries ROLE_PRE_AUTH. The Spring Security method-level @PreAuthorize checks on all endpoints except PATCH /api/usuarios/pass will reject these requests with 403 Forbidden. The user cannot use any feature until they complete the password change.
1

First login

The user calls POST /api/login with their temporary credentials. The response is a valid JWT — but with ROLE_PRE_AUTH embedded in the rol claim.
2

Change password

The user immediately calls PATCH /api/usuarios/pass with oldPassword (the temporary one) and newPassword. The backend sets cambiarPass = false and saves the record.
3

Re-login for full access

The user calls POST /api/login again. This time, cambiarPass is false, so getAuthorities() returns the real role (ROLE_USER, ROLE_ADMIN, or ROLE_SUPER_ADMIN). All endpoints are now accessible according to the user’s actual role.

​
Token storage (frontend)

The React frontend that ships with Comunidades Vecinos stores the JWT in localStorage under the key token: 
// After a successful login response
localStorage.setItem('token', jwtString);

// Attaching the token to API requests
const token = localStorage.getItem('token');
fetch('/api/usuarios/me', {
  headers: { Authorization: `Bearer ${token}` }
});
localStorage is readable by any JavaScript running on the page. If you deploy Comunidades Vecinos in a context where XSS attacks are a concern, consider switching to HttpOnly cookies so the token is never accessible to client-side scripts. The backend’s stateless design is compatible with either approach.

Build docs developers (and LLMs) love

Get started for freeTalk to us