Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gcapella0/agente-inteligente-expedientes/llms.txt

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

The API uses JWT tokens signed with HS256. Every token is signed using the JWT_SECRET_KEY environment variable (defaults to a development placeholder — always override this in production). Tokens expire after 480 minutes (8 hours), as defined by ACCESS_TOKEN_EXPIRE_MINUTES in security.py. Passwords are stored and verified using bcrypt via passlib.

​
POST /auth/login

Authenticate a user and receive a signed JWT token.
PropertyValue
MethodPOST
Path/auth/login
Auth requiredNo
Content-Typeapplication/json

​
Request body

​
email
string
required
The user’s registered email address.
​
password
string
required
The user’s plaintext password. Verified against the bcrypt hash stored in MongoDB.
{
  "email": "admin@uneg.edu.ve",
  "password": "admin123"
}

​
Response 200 — Success

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "usuario": {
    "email": "admin@uneg.edu.ve",
    "nombre_completo": "Administrador Sistema",
    "rol": "admin",
    "activo": true
  }
}
The usuario object in the response reflects the UsuarioResponse model — it never includes password_hash.

​
Error responses

StatusDetailCause
401Email o contraseña incorrectosEmail not found in the usuarios collection, or bcrypt verification failed
403Usuario inactivoUser document has activo: false

​
cURL example

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@uneg.edu.ve", "password": "admin123"}'
On first startup, if the usuarios MongoDB collection is empty, the system automatically inserts a default admin account: email admin@uneg.edu.ve / password admin123. Change this credential immediately in any non-development environment.

​
Using the token

All write endpoints require the token in the Authorization header: 
Authorization: Bearer <access_token>
verify_token (in dependencies.py) splits the header on whitespace, asserts the scheme is bearer, then calls decode_token which validates the HS256 signature and checks expiry.

​
Query-parameter fallback (?token=)

File-serving and SSE endpoints use verify_token_sse instead of verify_token. This dependency reads the token from a ?token= query parameter so browsers can load resources via <img src="...?token=..."> and <iframe> without custom headers.

​
Extract and reuse a token in shell scripts

# ── 1. Obtain token ────────────────────────────────────────────
TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@uneg.edu.ve", "password": "admin123"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# ── 2. Use token on a protected endpoint ───────────────────────
curl http://localhost:8000/agentes \
  -H "Authorization: Bearer $TOKEN"

​
POST /auth/crear-usuario

Create a new user account. Requires an authenticated admin.
PropertyValue
MethodPOST
Path/auth/crear-usuario
Auth requiredYes — admin role
Content-Typeapplication/json

​
Request body

​
email
string
required
Email address for the new account. Must be unique in the usuarios collection.
​
password
string
required
Plaintext password. Stored as a bcrypt hash — never persisted in cleartext.
​
nombre_completo
string
required
Full display name of the new user.
​
rol
string
default:"usuario"
Role to assign. Must be one of admin, usuario, or sistema (as defined in UsuarioCreate).
{
  "email": "docente@uneg.edu.ve",
  "password": "securepassword123",
  "nombre_completo": "Docente Ejemplo",
  "rol": "usuario"
}

​
Response 201 — Created

{
  "mensaje": "Usuario creado correctamente",
  "_id": "507f1f77bcf86cd799439012",
  "email": "docente@uneg.edu.ve",
  "rol": "usuario"
}

​
Error responses

StatusDetailCause
400El email ya está registradoA document with that email already exists
403Solo administradores pueden realizar esta acciónCaller’s rol is not admin

​
POST /auth/cambiar-password

Change the authenticated user’s own password.
PropertyValue
MethodPOST
Path/auth/cambiar-password
Auth requiredYes — any authenticated user
This endpoint identifies the target account from the JWT payload (sub claim), so a user can only change their own password. There is no admin override path on this endpoint.

​
Query parameters

​
password_actual
string
required
The user’s current password. Verified against the stored bcrypt hash before any change is made.
​
password_nuevo
string
required
The new plaintext password. Will be hashed with bcrypt and stored.

​
Response 200 — Success

{
  "mensaje": "Contraseña cambiada correctamente",
  "email": "docente@uneg.edu.ve"
}

​
Error responses

StatusDetailCause
401Contraseña actual incorrectaverify_password returned false
404Usuario no encontradoJWT sub doesn’t match any document

​
JWT payload structure

Every token produced by create_access_token encodes the following claims:
ClaimTypeDescription
substringUser email — the primary identity used by all handlers
rolstringUser’s assigned role (e.g. admin, usuario, sistema, docente, viewer) — reflects whatever role is stored in the usuarios collection
expintegerExpiration timestamp (Unix epoch, UTC)
iatintegerIssued-at timestamp (Unix epoch, UTC)

​
Role-based access

Two dependency functions in dependencies.py gate protected endpoints:
DependencyWho can passUsed by
verify_tokenAny user with a valid, unexpired token/auth/cambiar-password, most read endpoints
verify_adminOnly users with rol == "admin"/auth/crear-usuario, /usuarios/*, /admin/auditoria
When verify_admin is called but the token’s rol is not admin, the server returns: 
HTTP 403 Forbidden
{
  "detail": "Solo administradores pueden realizar esta acción"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us