Skip to content

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 UserCompany activa 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 fuerza POST /authenticate/refresh para 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 previa null), limpia la sesión y devuelve company_switch_partial_reauthenticate para pedir un nuevo login. Una respuesta 401 del refresh limpia la sesión como session_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 vinculadasCabecera X-Company-IdResultado
Exactamente 1AusenteSe asume esa empresa
2 o másAusenteSe rechazan operaciones que necesitan tenant
Cualquier númeroPresente y en el conjunto vinculadoEsa empresa es el contexto activo
Cualquier númeroPresente y no vinculada403 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:

CampoDescripción
userIdIdentificador del usuario
companyIdEmpresa activa en esta sesión
roleRol 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-empresa

El 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étodoRutaPúblicoDescripció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.