Esta página es parte de una habilidad de agente de codificación con IA y está escrita para agentes, no para humanos. Para la documentación de Base44 legible por humanos, consulta la documentación para desarrolladores.

Módulo Auth

Autenticación de usuario, registro y gestión de sesión mediante base44.auth.

Tipos TypeScript

Interfaz User

interface User {
  id: string;
  created_date: string;
  updated_date: string;
  email: string;
  full_name: string | null;
  disabled: boolean | null;
  is_verified: boolean;
  app_id: string;
  is_service: boolean;
  role: string;
  [key: string]: any; // Campos de esquema personalizados
}

Interfaz LoginResponse

interface LoginResponse {
  access_token: string;  // Token JWT
  user: User;           // Objeto de usuario completo
}

Interfaces de parámetros

RegisterParams

interface RegisterParams {
  email: string;                    // Requerido
  password: string;                 // Requerido
  turnstile_token?: string | null;  // Opcional: Cloudflare Turnstile para protección contra bots
  referral_code?: string | null;    // Opcional: código de referencia
}

VerifyOtpParams

interface VerifyOtpParams {
  email: string;     // Correo del usuario
  otpCode: string;   // Código OTP del correo
}

ResetPasswordParams

interface ResetPasswordParams {
  resetToken: string;   // Token del correo de restablecimiento de contraseña
  newPassword: string;  // Nueva contraseña a establecer
}

ChangePasswordParams

interface ChangePasswordParams {
  userId: string;          // ID de usuario
  currentPassword: string; // Contraseña actual para verificación
  newPassword: string;     // Nueva contraseña a establecer
}

Tipo Provider

type Provider = 'google' | 'microsoft' | 'facebook';

Métodos

Interfaz del módulo

interface AuthModule {
  // Información del usuario
  me(): Promise<User>;
  updateMe(data: Partial<Omit<User, 'id' | 'created_date' | 'updated_date' | 'app_id' | 'is_service'>>): Promise<User>;
  isAuthenticated(): Promise<boolean>;

  // Login/Logout
  loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<LoginResponse>;
  loginWithProvider(provider: Provider, fromUrl?: string): void;
  logout(redirectUrl?: string): void;
  redirectToLogin(nextUrl: string): void;

  // Gestión de tokens
  setToken(token: string, saveToStorage?: boolean): void;

  // Registro
  register(params: RegisterParams): Promise<any>;
  verifyOtp(params: VerifyOtpParams): Promise<any>;
  resendOtp(email: string): Promise<any>;

  // Gestión de usuarios
  inviteUser(userEmail: string, role: string): Promise<any>;

  // Gestión de contraseñas
  resetPasswordRequest(email: string): Promise<any>;
  resetPassword(params: ResetPasswordParams): Promise<any>;
  changePassword(params: ChangePasswordParams): Promise<any>;
}

Tabla de referencia de métodos

Método	Parámetros	Tipo de retorno	Descripción
`register()`	`params: RegisterParams`	`Promise<any>`	Crea una nueva cuenta de usuario
`loginViaEmailPassword()`	`email: string, password: string, turnstileToken?: string`	`Promise<LoginResponse>`	Autentica con correo/contraseña
`loginWithProvider()`	`provider: Provider, fromUrl?: string`	`void`	Inicia el flujo de inicio de sesión OAuth. Proveedores: `'google'` (por defecto), `'microsoft'`, `'facebook'` (habilita en configuración de app)
`me()`	Ninguno	`Promise<User>`	Obtiene el usuario autenticado actual
`updateMe()`	`data: Partial<User>`	`Promise<User>`	Actualiza el perfil del usuario actual
`logout()`	`redirectUrl?: string`	`void`	Redirige al logout del lado del servidor (borra cookies HTTP-only y sesión), luego a redirectUrl o URL actual
`redirectToLogin()`	`nextUrl: string`	`void`	⚠️ Evitar - Prefiere UI de login personalizada con `loginViaEmailPassword()` o `loginWithProvider()`
`isAuthenticated()`	Ninguno	`Promise<boolean>`	Comprueba si el usuario ha iniciado sesión
`setToken()`	`token: string, saveToStorage?: boolean`	`void`	Establece manualmente el token de autenticación
`inviteUser()`	`userEmail: string, role: string`	`Promise<any>`	Envía correo de invitación
`verifyOtp()`	`params: VerifyOtpParams`	`Promise<any>`	Verifica código OTP
`resendOtp()`	`email: string`	`Promise<any>`	Reenvía código OTP
`resetPasswordRequest()`	`email: string`	`Promise<any>`	Solicita restablecimiento de contraseña
`resetPassword()`	`params: ResetPasswordParams`	`Promise<any>`	Restablece contraseña con token
`changePassword()`	`params: ChangePasswordParams`	`Promise<any>`	Cambia contraseña de usuario

Ejemplos

Registrar nuevo usuario (flujo completo)

El registro requiere verificación de correo antes del login. Flujo completo:

Registrar - Crear la cuenta de usuario
Correo de verificación enviado - El usuario recibe un código OTP
Verificar OTP - El usuario introduce el código para verificar el correo
Iniciar sesión - El usuario ahora puede iniciar sesión

try {
  // Paso 1: Registrar el usuario
  await base44.auth.register({
    email: "user@example.com",
    password: "securePassword123",
    referral_code: "OPTIONAL_CODE",    // opcional
    turnstile_token: "CAPTCHA_TOKEN"   // opcional, para protección contra bots
  });
  console.log('Registration successful. Check email for OTP code.');

  // Paso 2: El usuario recibe un correo con código OTP (por ejemplo, "123456")

  // Paso 3: Verificar el código OTP
  await base44.auth.verifyOtp({
    email: "user@example.com",
    otpCode: "123456"  // código del correo de verificación
  });
  console.log('Email verified successfully.');

  // Paso 4: Ahora el usuario puede iniciar sesión
  const loginResponse = await base44.auth.loginViaEmailPassword(
    "user@example.com",
    "securePassword123"
  );
  console.log('Login successful:', loginResponse.user);

} catch (error) {
  console.error('Registration flow failed:', error.message);
  // Maneja errores específicos (ver sección Manejo de errores)
}

Importante: Los usuarios no pueden iniciar sesión hasta que completen la verificación OTP. Intentar llamar a loginViaEmailPassword antes de la verificación fallará.

Iniciar sesión con correo/contraseña

try {
  const response = await base44.auth.loginViaEmailPassword(
    "user@example.com",
    "password123",
    turnstileToken  // opcional: para protección contra bots
  );

  console.log('Login successful');
  console.log('User:', response.user);
  console.log('Token:', response.access_token);

  // El JWT se almacena automáticamente para solicitudes posteriores

} catch (error) {
  console.error('Login failed:', error.message);
  if (error.status === 401) {
    console.error('Invalid credentials');
  } else if (error.status === 403) {
    console.error('Email not verified. Please check your email for OTP.');
  }
}

Iniciar sesión con proveedor OAuth

Proveedores admitidos: 'google' (habilitado por defecto), 'microsoft' y 'facebook'. Habilita Microsoft o Facebook en la configuración de autenticación de tu app antes de usarlos.

// Redirigir a Google OAuth
base44.auth.loginWithProvider('google');

// Redirigir a Google OAuth y volver a la página actual después
base44.auth.loginWithProvider('google', window.location.href);

// Microsoft o Facebook (habilita en configuración de app primero)
base44.auth.loginWithProvider('microsoft');
base44.auth.loginWithProvider('facebook', '/dashboard');

Obtener usuario actual

try {
  const user = await base44.auth.me();

  if (user) {
    console.log('User ID:', user.id);
    console.log('Email:', user.email);
    console.log('Name:', user.full_name);
    console.log('Role:', user.role);
    console.log('Verified:', user.is_verified);
  } else {
    console.log('User not authenticated');
  }

} catch (error) {
  console.error('Failed to fetch user:', error.message);
  if (error.status === 401) {
    // Token expirado o inválido - navega a tu página de login personalizada
    navigate('/login');
  }
}

Actualizar perfil de usuario

try {
  const updatedUser = await base44.auth.updateMe({
    full_name: "John Doe",
    // Los campos de esquema personalizados pueden actualizarse aquí
    phone: "+1234567890",
    preferences: { theme: "dark" }
  });

  console.log('Profile updated:', updatedUser);

} catch (error) {
  console.error('Profile update failed:', error.message);
  if (error.status === 400) {
    console.error('Invalid data provided');
  } else if (error.status === 401) {
    console.error('Authentication required');
    navigate('/login');
  }
}

Comprobar estado de autenticación

try {
  const isLoggedIn = await base44.auth.isAuthenticated();

  if (isLoggedIn) {
    // Mostrar UI autenticada
    console.log('User is authenticated');
  } else {
    // Mostrar botón de login
    console.log('User is not authenticated');
  }

} catch (error) {
  console.error('Failed to check authentication:', error.message);
  // En error, tratar como no autenticado
}

Logout

Logout redirige al usuario al endpoint de logout del lado del servidor (/api/apps/auth/logout) para borrar cookies HTTP-only y la sesión, luego redirige a la URL dada (o a la página actual si se omite). Requiere un entorno de navegador.

// Logout: borra sesión mediante el servidor, luego redirige a la página actual
base44.auth.logout();

// Logout y redirigir a página de despedida después
base44.auth.logout("/goodbye");

// Logout y redirigir a página de inicio
base44.auth.logout("/");

Patrón de ruta protegida

// Usando una función de navegación (por ejemplo, useNavigate de React Router, router de Next.js)
async function requireAuth(navigate) {
  try {
    const user = await base44.auth.me();

    if (!user) {
      // Navega a tu página de login personalizada
      navigate('/login', { state: { returnTo: window.location.pathname } });
      return null;
    }

    return user;

  } catch (error) {
    console.error('Authentication check failed:', error.message);
    navigate('/login', { state: { returnTo: window.location.pathname } });
    return null;
  }
}

// Uso en tu app
async function loadProtectedPage(navigate) {
  const user = await requireAuth(navigate);
  if (!user) {
    // Navegará al login
    return;
  }

  // Continúa con lógica autenticada
  console.log('Welcome,', user.full_name);
}

Establecer token de autenticación

// ADVERTENCIA DE SEGURIDAD: Nunca codifiques tokens ni los expongas en código cliente
// Los tokens solo deben recibirse de flujos de autenticación seguros

// Establecer token y guardar en localStorage (por defecto)
base44.auth.setToken(receivedToken);

// Establecer token sin guardar en localStorage (sesión temporal)
base44.auth.setToken(receivedToken, false);

// Verificar que el token se estableció
try {
  const isAuthenticated = await base44.auth.isAuthenticated();
  if (!isAuthenticated) {
    console.error('Token validation failed');
  }
} catch (error) {
  console.error('Failed to set token:', error.message);
}

Invitar usuario a la aplicación

try {
  // Nota: Normalmente requiere privilegios de administrador
  const response = await base44.auth.inviteUser(
    "newuser@example.com",
    "user"  // o "admin"
  );

  console.log('Invitation sent successfully');

} catch (error) {
  console.error('Failed to invite user:', error.message);
  if (error.status === 403) {
    console.error('Insufficient permissions to invite users');
  } else if (error.status === 400) {
    console.error('Invalid email or role');
  }
}

Verificación OTP

try {
  // Verificar código OTP enviado al correo del usuario
  await base44.auth.verifyOtp({
    email: "user@example.com",
    otpCode: "123456"
  });

  console.log('OTP verified successfully');

} catch (error) {
  console.error('OTP verification failed:', error.message);
  if (error.status === 400) {
    console.error('Invalid or expired OTP code');
  } else if (error.status === 429) {
    console.error('Too many attempts. Please try again later.');
  }
}

// Reenviar OTP si es necesario
try {
  await base44.auth.resendOtp("user@example.com");
  console.log('OTP resent successfully');

} catch (error) {
  console.error('Failed to resend OTP:', error.message);
  if (error.status === 429) {
    console.error('Too many requests. Please wait before trying again.');
  }
}

Flujo de restablecimiento de contraseña

// Paso 1: Solicitar restablecimiento de contraseña
try {
  await base44.auth.resetPasswordRequest("user@example.com");
  console.log('Password reset email sent. Check your inbox.');

} catch (error) {
  console.error('Password reset request failed:', error.message);
  if (error.status === 429) {
    console.error('Too many requests. Please try again later.');
  }
  // Nota: Por seguridad, no reveles si el correo existe
}

// Paso 2: Restablecer contraseña con token del correo
try {
  await base44.auth.resetPassword({
    resetToken: "token-from-email",
    newPassword: "newSecurePassword123"
  });

  console.log('Password reset successfully. You can now log in.');

} catch (error) {
  console.error('Password reset failed:', error.message);
  if (error.status === 400) {
    console.error('Invalid or expired reset token');
  } else if (error.status === 422) {
    console.error('Password does not meet requirements');
  }
}

Cambiar contraseña

try {
  const currentUser = await base44.auth.me();

  if (!currentUser) {
    throw new Error('User must be authenticated to change password');
  }

  await base44.auth.changePassword({
    userId: currentUser.id,
    currentPassword: "oldPassword123",
    newPassword: "newSecurePassword456"
  });

  console.log('Password changed successfully');

} catch (error) {
  console.error('Password change failed:', error.message);
  if (error.status === 401) {
    console.error('Current password is incorrect');
  } else if (error.status === 422) {
    console.error('New password does not meet requirements');
  } else if (error.status === 403) {
    console.error('Not authorized to change this password');
  }
}

Manejo de errores

Escenarios de error comunes

El módulo auth puede lanzar varios errores. Aquí hay escenarios comunes y cómo manejarlos:

Errores de autenticación (401/403)

try {
  const user = await base44.auth.me();
} catch (error) {
  if (error.status === 401) {
    // Token expirado o inválido - navega a tu página de login personalizada
    navigate('/login');
  } else if (error.status === 403) {
    // Correo no verificado o permisos insuficientes
    console.error('Access denied:', error.message);
  }
}

Errores de validación (400/422)

try {
  await base44.auth.register({
    email: "invalid-email",
    password: "weak"
  });
} catch (error) {
  if (error.status === 400) {
    console.error('Invalid input:', error.message);
    // Maneja errores de validación
  } else if (error.status === 422) {
    console.error('Data validation failed:', error.details);
  }
}

Limitación de tasa (429)

try {
  await base44.auth.resendOtp("user@example.com");
} catch (error) {
  if (error.status === 429) {
    console.error('Too many requests. Please wait before trying again.');
    // Muestra cuenta regresiva o deshabilita el botón temporalmente
  }
}

Manejador de errores genérico

function handleAuthError(error) {
  switch (error.status) {
    case 400:
      return 'Invalid input. Please check your data.';
    case 401:
      return 'Authentication required. Redirecting to login...';
    case 403:
      return 'Access denied. You may need to verify your email.';
    case 404:
      return 'Resource not found.';
    case 422:
      return 'Validation failed. Please check your input.';
    case 429:
      return 'Too many requests. Please try again later.';
    case 500:
      return 'Server error. Please try again.';
    default:
      return 'An unexpected error occurred.';
  }
}

// Uso
try {
  await base44.auth.loginViaEmailPassword(email, password);
} catch (error) {
  console.error(handleAuthError(error));
}

Proveedores de autenticación

Configura los proveedores de autenticación en el panel de tu app:

Proveedores disponibles

Integrados (todos los planes):

Email/Password - Predeterminado, siempre habilitado
Google - Autenticación OAuth
Microsoft - Autenticación OAuth
Facebook - Autenticación OAuth

Proveedores SSO (plan Elite):

Okta
Azure AD
GitHub

Usar proveedores OAuth

Google – habilitado por defecto.
Microsoft – habilita en la configuración de autenticación de tu app antes de usarlo.
Facebook – habilita en la configuración de autenticación de tu app antes de usarlo.

// Iniciar el flujo de inicio de sesión OAuth
base44.auth.loginWithProvider('google');

// Volver a una página específica tras la autenticación
base44.auth.loginWithProvider('microsoft', '/dashboard');

// Valores admitidos: 'google', 'microsoft', 'facebook'

Disponibilidad de entorno

Entorno	Disponibilidad	Notas
Frontend	✅ Sí	Todos los métodos disponibles
Funciones de backend	✅ Sí	Usa `createClientFromRequest(req)` para cliente autenticado
Rol de servicio	❌ No	Los métodos de autenticación no están disponibles en el contexto de rol de servicio

Uso en frontend

// Uso estándar en navegador
const user = await base44.auth.me();

Uso en funciones de backend

import { createClientFromRequest } from "@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);

  // Obtiene el usuario del contexto de la solicitud
  const user = await base44.auth.me();

  // Operaciones de usuario aquí...
  return Response.json({ user });
});

Visibilidad de la app

Controla quién puede acceder a tu app en la configuración de la app:

Apps públicas

No se requiere login para acceso básico
Los usuarios pueden ver contenido público sin autenticación
Los usuarios autenticados obtienen funciones/datos adicionales

Apps privadas

Se requiere login para acceder a cualquier contenido
Los usuarios no autenticados son redirigidos automáticamente al login
Todo el contenido está protegido por defecto

Limitaciones

Opciones de UI de autenticación

Recomendado: Construye una UI de login/registro personalizada usando loginViaEmailPassword() y loginWithProvider() para control total sobre la experiencia de usuario y la marca
Alternativa: redirectToLogin() usa las páginas de autenticación alojadas de Base44 con personalización limitada

redirectToLogin() muestra las opciones de inicio de sesión y registro en la misma página
No hay un método redirectToSignup() separado
Los usuarios pueden cambiar entre login/registro en la página alojada
⚠️ Nota: Prefiere construir una UI de login personalizada para una mejor experiencia de usuario

Requisitos de contraseña

Se aplican requisitos mínimos de longitud y complejidad
Los requisitos no se exponen mediante API
Se devuelven errores de validación cuando no se cumplen los requisitos

Limitación de tasa

Las solicitudes de OTP tienen limitación de tasa para prevenir abusos
Las solicitudes de restablecimiento de contraseña tienen limitación de tasa
Los intentos de inicio de sesión pueden tener limitación de tasa con protección Turnstile

Gestión de tokens

Los JWT se almacenan automáticamente en localStorage por defecto
La expiración y renovación de tokens no se exponen en la API
Llama a me() o isAuthenticated() para verificar la validez del token

Mejores prácticas

1. Siempre maneja errores

try {
  await base44.auth.loginViaEmailPassword(email, password);
} catch (error) {
  // Siempre maneja errores de autenticación
  console.error('Login failed:', error.message);
}

2. Verifica la autenticación antes de acciones protegidas

const user = await requireAuth();
if (!user) return; // Redirigirá al login
// Procede con acción autenticada

3. Usa seguridad de tipos con TypeScript

import type { User, LoginResponse } from '@base44/sdk';

const user: User = await base44.auth.me();
const response: LoginResponse = await base44.auth.loginViaEmailPassword(email, password);

4. No codifiques credenciales

// ❌ MAL
base44.auth.setToken("hardcoded-token-here");

// ✅ BIEN
const token = await secureAuthFlow();
base44.auth.setToken(token);

5. Proporciona retroalimentación al usuario

try {
  await base44.auth.register(params);
  showSuccessMessage('Registration successful! Check your email for verification code.');
} catch (error) {
  showErrorMessage('Registration failed: ' + error.message);
}

6. Maneja la expiración de tokens con elegancia

try {
  const user = await base44.auth.me();
} catch (error) {
  if (error.status === 401) {
    // Borra el estado local y navega al login
    localStorage.clear();
    navigate('/login');
  }
}

// ✅ RECOMENDADO - Formulario de login personalizado con métodos directos
const handleLogin = async (email, password) => {
  try {
    const { user } = await base44.auth.loginViaEmailPassword(email, password);
    navigate('/dashboard');
  } catch (error) {
    setError(error.message);
  }
};

const handleGoogleLogin = () => {
  base44.auth.loginWithProvider('google', '/dashboard');
};

// ❌ EVITAR - Redirigir a página de login alojada
// base44.auth.redirectToLogin(window.location.href);

Esta página fue traducida usando IA. Para obtener la información más precisa y actualizada, consulta la versión en inglés.

​Módulo Auth

​Contenido

​Tipos TypeScript

​Interfaz User

​Interfaz LoginResponse

​Interfaces de parámetros

​RegisterParams

​VerifyOtpParams

​ResetPasswordParams

​ChangePasswordParams

​Tipo Provider

​Métodos

​Interfaz del módulo

​Tabla de referencia de métodos

​Ejemplos

​Registrar nuevo usuario (flujo completo)

​Iniciar sesión con correo/contraseña

​Iniciar sesión con proveedor OAuth

​Obtener usuario actual

​Actualizar perfil de usuario

​Comprobar estado de autenticación

​Logout

​Patrón de ruta protegida

​Establecer token de autenticación

​Invitar usuario a la aplicación

​Verificación OTP

​Flujo de restablecimiento de contraseña

​Cambiar contraseña

​Manejo de errores

​Escenarios de error comunes

​Errores de autenticación (401/403)

​Errores de validación (400/422)

​Limitación de tasa (429)

​Manejador de errores genérico

​Proveedores de autenticación

​Proveedores disponibles

​Usar proveedores OAuth

​Disponibilidad de entorno

​Uso en frontend

​Uso en funciones de backend

​Visibilidad de la app

​Apps públicas

​Apps privadas

​Limitaciones

​Opciones de UI de autenticación

​Login alojado (mediante redirectToLogin)

​Requisitos de contraseña

​Limitación de tasa

​Gestión de tokens

​Mejores prácticas

​1. Siempre maneja errores

​2. Verifica la autenticación antes de acciones protegidas

​3. Usa seguridad de tipos con TypeScript

​4. No codifiques credenciales

​5. Proporciona retroalimentación al usuario

​6. Maneja la expiración de tokens con elegancia

​7. Construye una UI de login personalizada (recomendado)

Módulo Auth

Contenido

Tipos TypeScript

Interfaz User

Interfaz LoginResponse

Interfaces de parámetros

RegisterParams

VerifyOtpParams

ResetPasswordParams

ChangePasswordParams

Tipo Provider

Métodos

Interfaz del módulo

Tabla de referencia de métodos

Ejemplos

Registrar nuevo usuario (flujo completo)

Iniciar sesión con correo/contraseña

Iniciar sesión con proveedor OAuth

Obtener usuario actual

Actualizar perfil de usuario

Comprobar estado de autenticación

Logout

Patrón de ruta protegida

Establecer token de autenticación

Invitar usuario a la aplicación

Verificación OTP

Flujo de restablecimiento de contraseña

Cambiar contraseña

Manejo de errores

Escenarios de error comunes

Errores de autenticación (401/403)

Errores de validación (400/422)

Limitación de tasa (429)

Manejador de errores genérico

Proveedores de autenticación

Proveedores disponibles

Usar proveedores OAuth

Disponibilidad de entorno

Uso en frontend

Uso en funciones de backend

Visibilidad de la app

Apps públicas

Apps privadas

Limitaciones

Opciones de UI de autenticación

Login alojado (mediante redirectToLogin)

Requisitos de contraseña

Limitación de tasa

Gestión de tokens

Mejores prácticas

1. Siempre maneja errores

2. Verifica la autenticación antes de acciones protegidas

3. Usa seguridad de tipos con TypeScript

4. No codifiques credenciales

5. Proporciona retroalimentación al usuario

6. Maneja la expiración de tokens con elegancia

7. Construye una UI de login personalizada (recomendado)