Flujos de Auth

Esta guia te ayuda a elegir el patron de autenticacion correcto para tu app en HeroMate.

Usala cuando tengas que decidir:

• si los usuarios pueden registrarse por su cuenta
• si el acceso debe ser solo por invitacion
• cuando usar endpoints jwt
• cuando usar endpoints api_key
• como separar llamadas frontend vs server

Regla Base

En HeroMate, los endpoints HTTP orientados a la aplicacion deben usar uno de estos modos:

• jwt: la request esta ligada a un usuario autenticado
• api_key: la request esta ligada a la key del proyecto, normalmente desde codigo server-side

No disenes endpoints publicos sin autenticacion.

Tabla Rapida De Decision

Flujo 1: App Publica Con Registro

Usa este flujo cuando:

• los usuarios crean su propia cuenta
• la app tiene login, perfil, dashboard o datos del usuario
• los workflows necesitan current_user o current_user_id

Configuracion recomendada:

1. Activa signup en Auth.
2. Mantiene la confirmacion por email activada salvo que tengas una razon fuerte para quitarla.
3. Usa dypai.auth.signUp() y dypai.auth.signInWithPassword() desde la app.
4. Protege los endpoints de negocio con auth_mode: "jwt".
5. Usa allowed_roles solo cuando necesites restricciones por rol.

Ejemplos tipicos:

• sitio SaaS
• app de clientes
• dashboard de usuario

const dypai = createClient(process.env.NEXT_PUBLIC_DYPAI_URL!);

await dypai.auth.signUp({
  email,
  password,
  full_name,
});

Usa jwt para acciones de la app y pantallas de usuario:

const { data } = await dypai.api.get('get_profile');

Flujo 2: App Privada Sin Registro Abierto

Usa este flujo cuando:

• los usuarios no deben poder crear cuenta por su cuenta
• tu equipo decide quien puede entrar
• es una app de cliente, portal interno, partner portal o herramienta privada

Configuracion recomendada:

1. No expongas signup abierto en la UI.
2. Crea usuarios desde flujos admin/backend.
3. Envia links de invitacion o enlaces de onboarding tipo recovery.
4. Deja que el usuario cree su password dentro de tu app.
5. Mantiene los endpoints de aplicacion en modo jwt.

Ejemplos tipicos:

• backoffice de empresa
• app privada para un cliente
• producto B2B solo por invitacion

Onboarding recomendado:

1. Un admin crea o invita al usuario.
2. El usuario abre un link de invitacion hacia la ruta callback de tu app.
3. El SDK emite PASSWORD_RECOVERY.
4. Tu UI muestra una pantalla para crear password.
5. A partir de ahi el usuario trabaja con sesion JWT normal.

dypai.auth.onAuthStateChange((event) => {
  if (event === 'PASSWORD_RECOVERY') {
    // Mostrar pantalla para crear password
  }
});

Flujo 3: App Interna Provisionada Por Admin

Es una version mas estricta del patron de app privada.

Usalo cuando:

• solo deben entrar empleados, operadores o colaboradores internos
• todas las cuentas las crea tu equipo
• los roles importan mucho (admin, editor, viewer, etc.)

Configuracion recomendada:

1. Sin signup publico.
2. Usuarios creados por admin.
3. El acceso funcional pasa por endpoints jwt.
4. Restringe endpoints sensibles con allowed_roles.

Ejemplo de reparto de roles:

• admin: gestion de usuarios y sistema
• editor: trabajo operativo
• viewer: acceso solo lectura

Flujo 4: Server-To-Server O Jobs Backend

Usa este flujo cuando:

• no existe una sesion de usuario humana
• un worker, cron, proxy webhook o backend necesita llamar al engine
• la request no debe depender de identidad de usuario

Configuracion recomendada:

1. Configura el endpoint destino con auth_mode: "api_key".
2. Llamalo solo desde codigo server-side.
3. Envia X-API-KEY.
4. No expongas la key en codigo del navegador.

Buenos sitios para usarlo:

• Next.js Route Handlers
• Next.js Server Actions
• Server Components que disparan logica backend
• workers Node
• jobs Python
• tareas cron

const dypai = createClient(
  process.env.DYPAI_URL!,
  process.env.DYPAI_API_KEY
);

await dypai.api.post('sync_data', payload);

Arquitectura Mixta: UI + Jobs De Backend

Es muy comun y normalmente es el setup mas limpio.

Patron:

• la UI/browser usa jwt
• los jobs backend e integraciones usan api_key

Ejemplo de separacion:

• create_order -> jwt
• sync_erp_orders -> api_key

Asi evitas exponer credenciales backend en el cliente y mantienes el flujo de usuario claro.

Que Evitar

Evita estos patrones:

• usar api_key desde codigo expuesto al navegador
• disenar endpoints abiertos/publicos sin auth
• mezclar logica especifica de usuario dentro de endpoints api_key
• enviar user_id manualmente cuando el contexto JWT deberia aportarlo
• usar api_key para acciones normales de UI cuando deberia ser jwt

Recomendacion Segun Tipo De App

App Consumer / SaaS

• Signup: si
• Login: si
• Modo principal: jwt
• Endpoints backend opcionales: api_key

App Privada De Cliente

• Signup: no
• Invitacion/provisioning: si
• Modo principal: jwt
• Flujo admin: invitacion / crear password

App Interna Operativa

• Signup: no
• Provisioning: solo admin
• Modo principal: jwt
• allowed_roles fuerte: si

Capa De Integracion En Segundo Plano

• Signup: no relevante
• Sesion de usuario: no
• Modo principal: api_key

Recomendacion Practica

Si tienes dudas, empieza asi:

1. Para pantallas de app orientadas al usuario, usa jwt.
2. Para automatizacion backend, usa api_key.
3. Si los usuarios no deben registrarse solos, quita el signup de la UI y usa invitacion/provisioning.

Siguientes Pasos

• Vision general de Auth
• Auth en el SDK
• API Builder: Endpoints
• Access Keys