Tenants y ambientes

¿Qué es un tenant?

TwiinsHRM es multi-tenant: cada empresa cliente es un tenant con su propio alias (por ejemplo twiins) y su propia base de datos. El alias identifica al tenant en cada petición mediante el header x-tenant-id.

En el portal web el tenant se deriva del subdominio ({alias}.twiinshrm.com). En una app móvil no hay subdominio, así que el alias debe configurarse o seleccionarse antes del login (por ejemplo, pidiendo el código de empresa en la primera pantalla) y persistirse localmente.

Precaución

El header x-tenant-id es obligatorio en TODAS las peticiones — incluidas las públicas como /auth/login y /tenancy. Sin él, la API responde 404 (tenant no encontrado). Y en las peticiones autenticadas debe coincidir con el claim tenant del JWT.

URLs base por ambiente

Ambiente	URL base
Producción	https://api-v4.twiinshrm.com/prod
Staging / pruebas	https://api-v4.twiinshrm.com/dev
Local (desarrollo del backend)	http://localhost:3000

Los paths de este manual se anexan a la URL base. Ejemplo en producción:

POST https://api-v4.twiinshrm.com/prod/auth/login
GET  https://api-v4.twiinshrm.com/prod/v2/muro/publications

Bootstrap del tenant (antes del login)

Estos endpoints son públicos (solo requieren x-tenant-id) y permiten configurar la app antes de autenticar:

sequenceDiagram
    participant App as App móvil
    participant API as th-core-api

    App->>API: GET /tenancy (x-tenant-id)
    API-->>App: Datos del tenant (valida que el alias existe)
    App->>API: GET /tenancy/parameters/login (x-tenant-id)
    API-->>App: Parámetros de login (SSO, branding)
    App->>App: Decidir pantalla: credenciales o SSO

GET /tenancy

Información básica del tenant. Úsalo para validar que el alias ingresado por el usuario existe antes de continuar.

GET /tenancy/parameters/login

Parámetros necesarios antes de autenticar. Los más relevantes para mobile:

Parámetro	Valores	Uso en la app
Login_SSO	'S' / 'N'	Si es 'S', el login es por Keycloak (SSO + PKCE); si no, formulario de credenciales.
Skin_Sistema	color hex	Color primario de la marca del tenant — úsalo para tematizar la app.

GET /tenancy/parameters

Catálogo completo de parámetros del tenant (requiere contexto de tenant). Aquí viven los flags de configuración que condicionan funcionalidades; cada módulo documenta los suyos.

GET /me/tenancy/products

Autenticado. Devuelve los productos/módulos habilitados para el usuario en ese tenant. Úsalo después del login para decidir qué secciones mostrar en el menú de la app: si un módulo no está habilitado, no debe aparecer.

Resumen del arranque de la app

1. Pedir/recuperar el alias del tenant → GET /tenancy para validarlo.
2. GET /tenancy/parameters/login → decidir login por credenciales o SSO, y aplicar branding.
3. Autenticar (ver Autenticación).
4. GET /auth/session + GET /me/tenancy/products → construir el home y el menú según el usuario.