Usuarios
¿Qué hace este módulo?
Gestiona las cuentas de usuario del sistema. Un usuario es una persona que puede autenticarse y pertenecer a una o varias empresas.
Conceptos clave
- Un usuario tiene email, nombre y contraseña.
- Un usuario puede pertenecer a varias empresas con roles diferentes en cada una.
- Crear un usuario es público (no requiere autenticación) — es el paso de registro.
- Listar y ver usuarios requieren autenticación (y aislamiento de tenant).
PATCH/DELETEexigen además rol OWNER o ADMIN.
Operaciones disponibles
Crear un usuario (registro)
POST /users
{
"name": "Ana García",
"email": "ana@empresa.com",
"password": "opcional, mínimo 6 caracteres"
}No requiere token. Es el punto de entrada para nuevos usuarios — tanto para el auto-registro público como para un administrador que da de alta a otra persona. Si el email ya existe, responde 409
Sin companyName, el usuario se une como member a una empresa activa marcada como isDefault=true. Si no hay una empresa por defecto activa, responde 503, informa que el registro no está disponible y no crea la cuenta.
Un usuario sin contraseña no puede iniciar sesión hasta que se le asigne una
password es opcional en el registro. Sin ella, la cuenta no puede autenticarse hasta que un OWNER/ADMIN la fije con PATCH /users/:id o el usuario complete el flujo de restablecimiento de contraseña.
Respuesta — el usuario creado más un access_token (JWT de ese usuario nuevo, pensado para que el propio flujo de auto-registro inicie sesión inmediatamente):
{
"id": "uuid",
"name": "Ana García",
"email": "ana@empresa.com",
"createdAt": "...",
"updatedAt": "...",
"access_token": "eyJ..."
}No usar access_token al crear un usuario en nombre de otro
Si un administrador autenticado llama a este endpoint para dar de alta a otra persona, debe descartar access_token — guardarlo sustituiría su propia sesión por la del usuario recién creado.
Registro como owner de una empresa nueva
POST /users
{
"name": "Ana García",
"email": "ana@empresa.com",
"password": "opcional, mínimo 6 caracteres",
"companyName": "Mi Empresa SL"
}Si se envía companyName, el usuario, una empresa nueva y su membresía owner se crean de forma atómica en una sola transacción — no se une a la empresa por defecto (isDefault=true) como member. El slug de la empresa se genera automáticamente a partir del nombre (en minúsculas, sin acentos, separado por guiones); si ya existe, se añade un sufijo numérico.
El access_token de la respuesta ya trae companyId y role: owner de la empresa recién creada, listo para usarse sin un segundo login.
Sin companyName, el comportamiento es el descrito arriba: se une a la empresa por defecto activa como member; si no existe, el registro falla con 503 y no crea la cuenta.
Listar usuarios
GET /users?page=1&limit=20Devuelve los usuarios de la empresa activa en la sesión.
Si el token no tiene empresa asociada:
- Owner o admin → devuelve todos los usuarios del sistema (vista de administración global).
- Cualquier otro rol (o sin rol) → devuelve una página vacía, nunca datos de otros tenants.
Paginación — page (default 1) y limit (default 20, máximo 100) son opcionales. La respuesta es un envelope, no un array plano:
{
"data": [/* usuarios de esta página */],
"total": 42,
"page": 1,
"limit": 20
}Una página fuera de rango no es un error: devuelve data: [] con total reflejando el conteo real.
Ver un usuario
GET /users/:idDevuelve el usuario solo si tiene una membresía activa en la empresa seleccionada. Sin contexto/membresía de tenant, no se resuelven ids arbitrarios: también un Super Admin necesita pertenecer a la empresa para consultar sus usuarios. En cualquier otro caso responde 404 — no se filtra existencia cross-tenant.
Actualizar un usuario
PATCH /users/:id
{
"name": "Ana García López",
"email": "ana.nueva@empresa.com",
"password": "opcional, mínimo 6 caracteres",
"isSuperAdmin": true
}Los cuatro campos son opcionales — se puede actualizar solo el nombre, solo el email, solo la contraseña, solo el flag de super admin, o cualquier combinación.
Permisos tenant
Los cambios tenant-scoped de perfil o membresía exigen una membresía activa en la empresa del objetivo y el rol OWNER/ADMIN que corresponda; un Super Admin sin membresía no obtiene acceso por su flag de plataforma. MEMBER/VIEWER reciben 403. El alcance de API keys privilegiadas sigue su contrato separado. La gestión global del flag isSuperAdmin no concede permiso sobre el resto de los datos del usuario.
password solo lo puede fijar un OWNER o ADMIN
Si el body incluye password y el rol del que hace la petición (según su JWT) no es owner ni admin, la petición devuelve 403 Forbidden y no se guarda nada.
isSuperAdmin solo lo puede otorgar/revocar otro super admin
Si el body incluye isSuperAdmin y quien hace la petición no es ya un super admin, la petición devuelve 403 Forbidden y no se guarda nada. Esto es intencional: nadie puede auto-promoverse. El primer super admin del sistema se otorga corriendo el script de seed (src/database/seed.ts) — ver la sección siguiente.
Super admin (rol a nivel de plataforma)
isSuperAdmin es un flag booleano en el usuario, independiente de cualquier membresía de empresa. El flag autoriza operaciones y catálogos explícitamente globales de plataforma. No permite listar, leer ni modificar datos de una empresa tenant, ni omite sus permisos de rol. Para usar una empresa, el Super Admin necesita allí una membresía UserCompany activa y queda sujeto a su rol/grants, como cualquier otro miembro. X-Company-Id solo selecciona una membresía activa; no concede acceso
El flag viaja en el JWT como una foto del momento del login, igual que role, pero se re-verifica contra la base de datos en cada petición que lo reclama como true — así que revocar el super admin a alguien surte efecto en su siguiente petición, no hasta que caduque el token (hasta 90 días).
Cómo se otorga el primer super admin: corriendo el script de seed apuntando SEED_ADMIN_EMAIL a la cuenta que se quiere promover. El script promueve esa cuenta de forma idempotente en cada ejecución.
Límite de acceso tenant
El header no autoriza el acceso por sí mismo. Cualquier JWT de usuario, incluido el de un Super Admin, necesita una membresía UserCompany activa para la empresa indicada. La política actual rechaza la selección de una empresa no miembro y usa su rol/grants vigentes; la implementación se realiza en.documenta el bypass anterior como histórico y queda supersedido por para acceso tenant.
Eliminar un usuario
DELETE /users/:idDevuelve 204 No Content si se eliminó correctamente. Requiere OWNER o ADMIN (mismo gate que PATCH) y el objetivo debe pertenecer al tenant activo.
Relación con empresas
Los usuarios no están directamente vinculados a una empresa en su registro. La vinculación ocurre en dos momentos:
- Manualmente — un administrador añade al usuario a su empresa desde el módulo de Empresas.
- Por invitación — el usuario acepta una invitación enviada por email.
→ Ver Invitaciones y Empresas para más detalle.
Compañía última usada
Preferencia de sesión del usuario autenticado, consumida por el SDK browser para auto-seleccionar tenant tras el login.
| Método | Ruta | Auth | Descripción |
|---|---|---|---|
| GET | /users/me/last-used-company | JWT usuario | Devuelve { companyId } o null |
| PUT | /users/me/last-used-company | JWT usuario | Persiste { companyId } si hay membresía |
Almacenamiento: columna users.last_used_company_id. El login (POST /authenticate/token) usa esta preferencia cuando el body no trae companyId (ver Autenticación).