Autenticación
¿Qué hace este módulo?
Gestiona el acceso al sistema. Cualquier usuario o aplicación que quiera usar la API necesita pasar primero por aquí para obtener un token de acceso (JWT).
Flujos de autenticación
1. Login de usuario
El flujo más habitual. El usuario envía su email y contraseña y recibe un token.
POST /authenticate/token
{
"username": "usuario@empresa.com",
"password": "su-contraseña",
"companyId": "uuid-opcional" ← si pertenece a varias empresas
}Respuesta: { access_token, refresh_token }. El access JWT autentica las peticiones; el refresh JWT (tokenType: refresh, TTL más largo) solo sirve para renovar la sesión vía POST /authenticate/refresh — no es válido como Authorization: Bearer.
Credenciales inválidas → 401 Unauthorized con el mensaje genérico Invalid credentials (sin revelar si falló el email o la contraseña).
Si el usuario pertenece a varias empresas y no indica companyId, el sistema selecciona automáticamente la última empresa usada por ese usuario (si sigue siendo miembro); si no hay última usada conocida, la primera membresía por orden de alta (createdAt ASC). Esa elección se guarda en users.last_used_company_id para el siguiente login.
1b. Renovar sesión (refresh)
Cuando el access token caduca o está próximo a caducar, el cliente (SDK browser) envía el refresh JWT en el body:
POST /authenticate/refresh
{
"refresh_token": "<refresh-jwt>"
}Respuesta: un nuevo par { access_token, refresh_token }. Token inválido, caducado o un access JWT pasado como refresh → 401 Unauthorized. Público; rate limit 20 peticiones/min por IP. Los login de app client (POST /authenticate/apps) no emiten refresh.
Custodia: el SDK browser guarda access y refresh solo en memoria de la instancia; el host no los persiste como fuente de verdad y no usa cookies HttpOnly para este contrato. Tras un 401 de refresh, getSnapshot() queda no autenticado y el host debe volver a hacer login.
Compañía última usada (contrato SDK)
El SDK browser puede leer y persistir la compañía activa del usuario:
GET /users/me/last-used-company
→ { "companyId": "uuid" | null }
PUT /users/me/last-used-company
{ "companyId": "uuid" }
→ { "companyId": "uuid" }Requiere JWT de usuario. PUT responde 403 si el usuario no es miembro de esa empresa. Tras un login exitoso (con o sin companyId en el body), el API también actualiza la última usada.
auth.selectCompany(companyId) y su alias auth.changeCompany(companyId) conservan la misma firma pública, pero el SDK aplica dos semánticas internas:
- Super Admin: puede seleccionar una empresa solo si tiene una membresía
UserCompanyactiva en ella; se aplican su rol/grants actuales. El cambio de contexto no modifica la preferencia del usuario ni necesita renovar el JWT. - Usuario humano: lee la preferencia anterior, la guarda con
PUT, y fuerzaPOST /authenticate/refreshpara que el nuevo JWT incluya la empresa y el rol seleccionados. Si el refresh falla, el SDK restaura una preferencia anterior no nula cuando puede verificarlo; si no puede restaurarla (incluida una preferencia previanull), limpia la sesión y devuelvecompany_switch_partial_reauthenticatepara pedir un nuevo login. Una respuesta 401 del refresh limpia la sesión comosession_expired.
Las selecciones SDK se procesan en orden. Una operación pendiente se cancela si login/register, logout, clearSession o clearActiveCompany cambia la generación de sesión. Una selección no convierte la empresa activa de un super admin en una membresía, y el API no relaja la comprobación de pertenencia del endpoint PUT.
2. Login de aplicación
Para servicios o procesos automatizados (workers, integraciones) que necesitan acceso a la API sin un usuario humano detrás.
POST /authenticate/apps
{
"clientId": "id-del-cliente",
"clientSecret": "secreto-del-cliente"
}Los clientes autorizados se crean previamente con POST /authenticate/authorized-client?magicWord=<palabra> (uso CLI/script). El clientSecret se genera aleatoriamente y solo se muestra una vez en la respuesta de creación (o de rotación); en base de datos solo se guarda su hash, nunca el valor en texto plano. Si la palabra mágica no coincide (o falta), la API responde 401 Unauthorized con el mensaje genérico Invalid credentials no un 200 con cuerpo de texto.
Rotar el secreto de un cliente autorizado
Un super admin de la plataforma (isSuperAdmin === true) puede rotar el clientSecret de un cliente ya creado sin tener que recrearlo — útil si el secreto se filtró o simplemente toca renovarlo periódicamente.
POST /authenticate/authorized-clients/:id/rotate
Authorization: Bearer <token-de-super-admin>Respuesta: el mismo clientId, con un clientSecret nuevo (visible una única vez, igual que al crear el cliente). El secreto anterior deja de funcionar de inmediato — no hay periodo de gracia. Los JWT que ya se hubieran emitido con el secreto anterior siguen siendo válidos hasta que caduquen por su cuenta; esta acción solo bloquea nuevos intentos de login con el secreto viejo.
Solo super admin
Cualquier otro usuario autenticado recibe 403 Forbidden. Rotar un id que no existe devuelve 404.
Gestionar app clients desde el panel (listar, crear, eliminar)
Además de la creación por magicWord (uso CLI/script) y la rotación de arriba, un super admin puede gestionar los app clients por completo desde el panel, sin necesitar el magicWord:
GET /authenticate/authorized-clients
Authorization: Bearer <token-de-super-admin>Devuelve la lista completa (id, clientId, name, createdAt), sin exponer nunca el hash del secreto. Lista vacía si todavía no hay ninguno.
POST /authenticate/authorized-clients
Authorization: Bearer <token-de-super-admin>
{
"name": "mi-servicio"
}Crea un app client igual que la vía magicWord, pero autenticado por JWT en vez de por palabra mágica. El clientSecret se muestra una única vez en la respuesta, igual que al crear vía magicWord o al rotar.
DELETE /authenticate/authorized-clients/:id
Authorization: Bearer <token-de-super-admin>Elimina el app client permanentemente (204). Los JWT que ya se hubieran emitido para ese clientId siguen siendo válidos hasta que caduquen por su cuenta — no hay revocación retroactiva, igual que al rotar. Un intento de login con el clientId eliminado falla con el mismo 401 que un clientId que nunca existió.
Vincular empresas a un app client
El objeto app client es global, pero sus asociaciones con empresas son tenant-scoped. Un Super Admin puede leer o cambiar un vínculo solo si tiene membresía activa y rol OWNER/ADMIN en esa empresa; la lista se limita a sus membresías. La asociación se reevalúa para siguientes peticiones. El JWT tokenType: app sigue consultando en vivo los vínculos activos; sin empresas vinculadas autentica pero no puede operar sobre datos de tenant (corte duro).
Contexto de empresa activa (mismo RequestContext / getTenantId() que el resto de actores):
| Empresas vinculadas | Cabecera X-Company-Id | Resultado |
|---|---|---|
| Exactamente 1 | Ausente | Se asume esa empresa |
| 2 o más | Ausente | Se rechazan operaciones que necesitan tenant |
| Cualquier número | Presente y en el conjunto vinculado | Esa empresa es el contexto activo |
| Cualquier número | Presente y no vinculada | 403 Forbidden |
GET /authenticate/authorized-clients/:id/companies
Authorization: Bearer <token-de-super-admin>POST /authenticate/authorized-clients/:id/companies
Authorization: Bearer <token-de-super-admin>
{
"companyId": "uuid-de-empresa"
}DELETE /authenticate/authorized-clients/:id/companies/:companyId
Authorization: Bearer <token-de-super-admin>Solo super admin
Las rutas de vínculo de empresas (igual que listar/crear/eliminar app clients) devuelven 403 Forbidden si el llamante no es super admin de plataforma.
Vincular mi empresa a un app client (OWNER/ADMIN)
Un OWNER o ADMIN puede vincular solo su empresa activa a un app client que ya conoce por su clientId público. No hay listado global de app clients para estos roles, ni forma de ver o modificar otras empresas vinculadas al mismo client.
POST /authenticate/app-clients/:clientId/company
Authorization: Bearer <token-de-owner-o-admin>Sin body: la empresa se toma del contexto de tenant del JWT. Idempotente si ya estaba vinculada. 404 si el clientId no existe; 403 si el rol no es OWNER/ADMIN.
DELETE /authenticate/app-clients/:clientId/company
Authorization: Bearer <token-de-owner-o-admin>Desvincula solo la empresa activa (204). Las demás empresas del client no se tocan.
El token JWT
El token contiene:
| Campo | Descripción |
|---|---|
userId | Identificador del usuario |
companyId | Empresa activa en esta sesión |
role | Rol del usuario en esa empresa (owner, admin, member, viewer) |
Importante
El token conserva una foto del rol y la empresa al iniciar sesión, pero para una operación tenant-scoped el servidor debe comprobar la membresía y el rol/grants actuales de esa empresa. Revocar la membresía o cambiar sus permisos debe afectar las siguientes peticiones.
Seleccionar empresa sin volver a hacer login
Un JWT de usuario puede seleccionar otra empresa con una membresía UserCompany activa usando la cabecera:
X-Company-Id: uuid-de-la-otra-empresaEl servidor valida la membresía antes de conceder contexto tenant-scoped y aplica su rol/grants actuales. El rol Super Admin de plataforma no permite seleccionar empresas ajenas; una empresa sin membresía activa se deniega. Sin la cabecera, el companyId del JWT también requiere una membresía activa.
Un app client puede seleccionar solo una empresa vinculada activamente a ese client. Las API keys siguen ligadas a su empresa e ignoran esta cabecera para ampliar el alcance. Ver Multi-tenancy.
He olvidado mi contraseña
Desde la pantalla de login, un usuario que no recuerda su contraseña puede solicitar un enlace de restablecimiento sin necesidad de estar autenticado.
1. Solicitar el restablecimiento
POST /authenticate/forgot-password
{
"email": "usuario@empresa.com"
}Respuesta: siempre la misma, exista o no una cuenta con ese email — por seguridad, este endpoint nunca revela si un correo está registrado. Si el email existe, se envía un correo con un enlace del tipo https://tu-dominio/reset-password?token=.... El enlace caduca pasadas unas horas (configurable, por defecto 2).
2. Establecer la nueva contraseña
POST /authenticate/reset-password
{
"token": "token-recibido-por-email",
"newPassword": "nueva-contraseña"
}El token solo puede usarse una vez. Si ha caducado, ya se usó, o no existe, la petición se rechaza con un error. La actualización de la contraseña y el marcado del token como usado ocurren en la misma transacción de base de datos (con bloqueo de fila en Postgres), de modo que dos peticiones concurrentes con el mismo token no pueden completar ambas. Al restablecer la contraseña, cualquier otro enlace de restablecimiento pendiente para ese mismo usuario también queda invalidado por seguridad.
TIP
Esto es distinto de que un OWNER/ADMIN cambie la contraseña de otro miembro del equipo desde PATCH /users/:id — ese es un flujo administrativo separado, no el de autoservicio descrito aquí.
Endpoints
| Método | Ruta | Público | Descripción |
|---|---|---|---|
POST | /authenticate/token | ✅ | Login de usuario — limitado a 5 peticiones/minuto por IP |
POST | /authenticate/refresh | ✅ | Renovar access/refresh con refresh_token — limitado a 20 peticiones/minuto por IP |
POST | /authenticate/apps | ✅ | Login de aplicación |
POST | /authenticate/authorized-client | ✅ (?magicWord=; 401 si incorrecta) | Crear cliente autorizado |
POST | /authenticate/authorized-clients/:id/rotate | ❌ (solo super admin) | Rotar el clientSecret de un cliente autorizado |
GET | /authenticate/authorized-clients | ❌ (solo super admin) | Listar todos los app clients (sin exponer el hash del secreto) |
POST | /authenticate/authorized-clients | ❌ (solo super admin) | Crear un app client vía JWT, sin magicWord |
DELETE | /authenticate/authorized-clients/:id | ❌ (solo super admin) | Eliminar permanentemente un app client |
GET | /authenticate/authorized-clients/:id/companies | ❌ (JWT + OWNER/ADMIN miembro) | Listar solo vínculos de empresas donde el actor tiene membresía activa |
POST | /authenticate/authorized-clients/:id/companies | ❌ (JWT + OWNER/ADMIN miembro) | Vincular una empresa donde el actor tiene membresía activa |
DELETE | /authenticate/authorized-clients/:id/companies/:companyId | ❌ (JWT + OWNER/ADMIN miembro) | Desvincular una empresa donde el actor tiene membresía activa |
POST | /authenticate/app-clients/:clientId/company | ❌ (OWNER/ADMIN) | Vincular la empresa activa al app client |
DELETE | /authenticate/app-clients/:clientId/company | ❌ (OWNER/ADMIN) | Desvincular la empresa activa del app client |
POST | /authenticate/forgot-password | ✅ | Solicitar restablecimiento de contraseña — limitado a 5 peticiones/minuto por IP |
POST | /authenticate/reset-password | ✅ | Establecer nueva contraseña con el token recibido |
Límite de peticiones (rate limiting)
Los endpoints públicos más sensibles del sistema (login, solicitud de restablecimiento de contraseña, creación pública de usuarios en POST /users y el receptor de webhooks en POST /webhooks/:provider) devuelven 429 Too Many Requests si se supera el límite permitido por IP en una ventana de 1 minuto. Esto protege contra ataques de fuerza bruta y abuso automatizado.