Gestor Financiero API Authentication — Login and Sessions

The Gestor Financiero API uses a session-cookie authentication model — there are no API keys or long-lived tokens to manage. When you log in, the server creates a server-side session and delivers two cookies to the browser: an HttpOnly sesion cookie that carries the session token, and a JavaScript-readable csrftoken cookie used for CSRF protection. Every subsequent request that changes state must echo that CSRF token back in the X-CSRF-Token request header. Sessions expire automatically 8 hours after they are created, and the server enforces brute-force protection at the username level.

Submit credentials as a JSON body. This route has a stricter rate limit (10 requests per minute per IP) than the rest of the API.

Request body

usuario

string

required

The account username. Maximum 50 characters.

password

string

required

The account password. Maximum 128 characters.

{ "usuario": "admin", "password": "yourpassword" }

Success response (200)

On a successful login the response body contains the authenticated user’s profile and the server sets two cookies on the response.

usuario

string

The account username.

nombre

string

The user’s display name.

rol

string

The user’s role: either admin or empleado.

tema

string

The user’s preferred UI theme: oscuro, claro, or sistema.

{ "usuario": "admin", "nombre": "Administrador", "rol": "admin", "tema": "oscuro" }

Cookies set on success

Cookie	HttpOnly	Expiry	Purpose
`sesion`	✅ Yes	8 hours	Carries the session token. Never readable by JavaScript.
`csrftoken`	❌ No	8 hours	Must be read by JavaScript and sent as the `X-CSRF-Token` header on mutating requests.

Both cookies are set with SameSite=Strict and Path=/.

Error responses

Status	When
401	Username not found or password is incorrect.
429	Rate limit reached (10 req/min) or username is locked out after repeated failures.

Example — logging in with curl

curl -s -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{"usuario": "admin", "password": "yourpassword"}' \
  --cookie-jar cookies.txt

The --cookie-jar cookies.txt flag saves both cookies to disk so that subsequent requests can include them automatically.

Making Authenticated Requests

Once you have a valid session, every request must include the sesion cookie. In a browser this happens automatically because the cookie is HttpOnly and the credentials: "include" fetch option is set. With curl, point to the saved cookie file with --cookie.

Read-only requests (GET)

No CSRF token is needed for safe HTTP methods (GET, HEAD, OPTIONS).

# Authenticated GET — read the project list
curl -s http://localhost:8000/proyectos \
  --cookie cookies.txt

Mutating requests (POST, PUT, PATCH, DELETE)

For any request that changes server state you must also include the X-CSRF-Token header whose value equals the current csrftoken cookie. The server compares them with a constant-time comparison; a mismatch returns HTTP 403.

# Read the CSRF token from the cookie jar
CSRF=$(grep csrftoken cookies.txt | awk '{print $NF}')

# Authenticated POST with CSRF token — create a project
curl -s -X POST http://localhost:8000/proyectos \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  --cookie cookies.txt \
  -d '{
    "nombre": "Remodelación Oficina",
    "cliente": "Empresa XYZ",
    "tipo": "Construcción",
    "total": "15000.00",
    "fecha_inicio": "2024-06-01"
  }'

In JavaScript, the frontend reads the token from document.cookie and injects it automatically for all POST, PUT, PATCH, and DELETE requests:

// Simplified from frontend/src/servicios/api.js
const m = document.cookie.match(/(?:^|; )csrftoken=([^;]*)/);
const csrf = m ? decodeURIComponent(m[1]) : null;

fetch("http://localhost:8000/proyectos", {
  method: "POST",
  credentials: "include",               // send the sesion cookie
  headers: {
    "Content-Type": "application/json",
    "X-CSRF-Token": csrf,               // echo the csrftoken cookie value
  },
  body: JSON.stringify({ /* ... */ }),
});

Checking the Current Session

GET /yo returns the profile of the currently authenticated user without requiring any extra parameters. It is the standard way to verify that a session cookie is still valid on page load.

curl -s http://localhost:8000/yo \
  --cookie cookies.txt

{ "usuario": "admin", "nombre": "Administrador", "rol": "admin", "tema": "oscuro" }

Returns 401 if the session is missing or has already expired.

Logout

POST /logout deletes the server-side session record and clears both cookies from the browser. After this call all subsequent requests with the old cookies will return 401.

CSRF=$(grep csrftoken cookies.txt | awk '{print $NF}')

curl -s -X POST http://localhost:8000/logout \
  -H "X-CSRF-Token: $CSRF" \
  --cookie cookies.txt \
  --cookie-jar cookies.txt

{ "ok": true }

Session Expiry

Sessions expire 8 hours after they are created. The expiry timestamp is stored server-side; the session is validated — and cleaned up — on every request. When a session expires the API returns 401. The frontend reacts to any 401 response (except on /login itself) by clearing the local user record and reloading the page, which redirects back to the login screen.

The Secure flag on both cookies is set to True only when ENTORNO=produccion. In development (ENTORNO=desarrollo, the default), cookies are sent over plain HTTP so that local testing works without TLS. Always set ENTORNO=produccion in any internet-facing deployment.

Brute-Force Protection

After 5 consecutive failed login attempts for the same username, that username is locked out for 15 minutes. The lockout counter is per-username, not per-IP, so it cannot be bypassed by rotating IP addresses. During a lockout, login attempts for that username immediately return HTTP 429 with no password verification performed (to avoid timing-based enumeration). The counter resets to zero on a successful login.

Constant	Value
Max failed attempts before lockout	5
Lockout duration	15 minutes
HTTP status during lockout	429

Roles and Authorisation

The rol field returned by /login and /yo controls access to admin-only endpoints. There are exactly two roles:

Role	Description
`admin`	Full access to all endpoints, including user management (`/usuarios`).
`empleado`	Access to all non-admin endpoints. Cannot access user-management routes.

Attempting to call an admin-only endpoint with an empleado session returns HTTP 403:

{ "detail": "Solo un administrador puede hacer esto." }

The principal administrator account (created automatically on first run) cannot be edited or deleted, even by other admins. Attempts return HTTP 403.

Overview

Endpoints

Gestor Financiero API Authentication — Login and Sessions

Request body

Success response (200)

Cookies set on success

Error responses

Example — logging in with curl

Making Authenticated Requests

Read-only requests (GET)

Mutating requests (POST, PUT, PATCH, DELETE)

Checking the Current Session

Logout

Session Expiry

Brute-Force Protection

Roles and Authorisation

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Login

​Request body

​Success response (200)

​Cookies set on success

​Error responses

​Example — logging in with curl

​Making Authenticated Requests

​Read-only requests (GET)

​Mutating requests (POST, PUT, PATCH, DELETE)

​Checking the Current Session

​Logout

​Session Expiry

​Brute-Force Protection

​Roles and Authorisation

Build docs developers (and LLMs) love

Login

Request body

Success response (200)

Cookies set on success

Error responses

Example — logging in with curl

Making Authenticated Requests

Read-only requests (GET)

Mutating requests (POST, PUT, PATCH, DELETE)

Checking the Current Session

Logout

Session Expiry

Brute-Force Protection

Roles and Authorisation