URLs y Dominios

Concepto

Cada tenant tiene un alias unico que se usa como subdominio. El hostname identifica implicitamente al tenant sin que el usuario lo digite. Los clientes pueden configurar dominios custom (CNAME) para white-labeling completo.

Estructura de URLs

URLs de plataforma (gestionadas por Reimagine Tech)

Componente	Patron	Ejemplo
Panel Admin	dash.{tenant-alias}.reimaginetech.io	dash.fintech-abc.reimaginetech.io
Ejecucion publica	validate.{tenant-alias}.reimaginetech.io/{token}	validate.fintech-abc.reimaginetech.io/abc123
API	api.{tenant-alias}.reimaginetech.io/v1/{resource}	api.fintech-abc.reimaginetech.io/v1/credits
Documentacion	docs.reimaginetech.io	docs.reimaginetech.io

Con organizaciones

Patron	Ejemplo	Resolucion
{org}.{tenant}.reimaginetech.io	digital.fintech-abc.reimaginetech.io	tenant: fintech-abc, org hint: digital
{tenant}.reimaginetech.io	fintech-abc.reimaginetech.io	tenant: fintech-abc, sin org hint

URLs con CNAME del cliente (white-label)

El cliente configura en su DNS:

validacion.clienteabc.com      CNAME  validate.fintech-abc.reimaginetech.io
panel.clienteabc.com           CNAME  dash.fintech-abc.reimaginetech.io
api.clienteabc.com             CNAME  api.fintech-abc.reimaginetech.io

El usuario final ve el dominio del cliente, no el de Imagy.

Versionamiento de API

La version se incluye en el path de la URL:

api.{tenant-alias}.reimaginetech.io/v1/credits
api.{tenant-alias}.reimaginetech.io/v1/flows
api.{tenant-alias}.reimaginetech.io/v2/credits

Regla	Descripcion
Version en URL	/v1/, /v2/, etc.
Version actual	v1 (MVP)
Backward compatible	Agregar campos o endpoints nuevos no requiere nueva version
Breaking change	Eliminar campos o cambiar estructura requiere nueva version
Soporte paralelo	Al lanzar v2, v1 sigue activa minimo 6 meses
Deprecation	Header Sunset: {date} en respuestas de version deprecated

Resolucion de Tenant desde Hostname

Orden de resolucion

1. Cache en Valkey (domain_resolve:{hostname})
2. Buscar hostname exacto en tabla tenant_domains (soporta CNAMEs custom)
3. Parsear patron {app}.{tenant-alias}.reimaginetech.io
4. Buscar tenant por alias
5. Si no se encuentra: 404

Resolucion por Header (APIs internas)

Para llamadas programaticas y service-to-service, el tenant se resuelve del JWT:

Prioridad	Fuente	Uso
1	JWT claim tenant_id	Siempre presente en requests autenticados
2	Hostname (subdominio)	Apps web, white-label
3	Query param cid	Fallback para desarrollo/testing

Modelo de Datos

CREATE TABLE tenant_domains (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    domain_type VARCHAR(20) NOT NULL
        CHECK (domain_type IN ('primary', 'cname', 'custom')),
    hostname VARCHAR(255) NOT NULL,
    is_verified BOOLEAN NOT NULL DEFAULT false,
    verified_at TIMESTAMPTZ,
    ssl_status VARCHAR(20) NOT NULL DEFAULT 'pending'
        CHECK (ssl_status IN ('pending', 'active', 'failed')),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT uq_tenant_domains_hostname UNIQUE (hostname)
);

CREATE INDEX idx_tenant_domains_lookup
    ON tenant_domains(hostname) WHERE is_verified = true;

Tipos de Dominio

Tipo	Descripcion	Verificacion	Ejemplo
primary	Generado automaticamente al crear tenant	No requiere	fintech-abc.reimaginetech.io
cname	CNAME del cliente apuntando a nuestro dominio	Verificacion DNS	validacion.clienteabc.com
custom	Dominio completamente custom	Verificacion DNS + TLS	id.empresa.co

Verificacion de Dominio Custom

Certificados TLS

Escenario	Solucion
Subdominios propios *.reimaginetech.io	Wildcard certificate en ACM
Subdominios de tenant *.fintech-abc.reimaginetech.io	Wildcard por tenant o SAN
CNAME del cliente	ACM con DNS validation

En AWS

CloudFront / ALB
├── Default cert: *.reimaginetech.io (wildcard)
├── SNI cert: *.fintech-abc.reimaginetech.io
├── SNI cert: *.cooperativa-xyz.reimaginetech.io
└── SNI cert: validacion.clienteabc.com (ACM DNS validation)

Cache de Resolucion

Key	TTL	Contenido	Invalidacion
domain_resolve:{hostname}	5 min	{tenant_id, alias, verified}	Al agregar/verificar/eliminar dominio
tenant_cache:{code}	5 min	{id, code, name, status}	Al crear/actualizar/suspender tenant

Endpoints API

Metodo	Endpoint	Descripcion	Rol
GET	/api/v1/tenants/{id}/domains	Listar dominios del tenant	tenant_admin
POST	/api/v1/tenants/{id}/domains	Agregar dominio custom	tenant_admin
POST	/api/v1/tenants/{id}/domains/{domainId}/verify	Verificar dominio	tenant_admin
DELETE	/api/v1/tenants/{id}/domains/{domainId}	Eliminar dominio	tenant_admin
GET	/api/v1/domains/resolve/{hostname}	Resolver hostname a tenant (interno)	system

Consideraciones Multi-Region

Para tenants en diferentes regiones (data residency):

Region	Dominio base	Infraestructura
Americas	reimaginetech.io	us-east-1
Europe	eu.reimaginetech.io	eu-west-1
APAC	ap.reimaginetech.io	ap-southeast-1

El tenant se asigna a una region al momento del onboarding. Los datos nunca salen de la region configurada. Route 53 con latency-based routing dirige al cluster correcto.

Reglas

• El alias del tenant es inmutable despues de crearse (se usa en URLs)
• Los alias deben ser unicos globalmente
• Formato de alias: ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$
• Aliases reservados: admin, api, auth, dash, docs, validate, www, app, system
• Un tenant puede tener multiples dominios custom
• Solo un dominio primary (generado automaticamente)
• Los dominios custom requieren verificacion DNS antes de activarse
• El certificado TLS se provisiona automaticamente via ACM despues de la verificacion