Questa pagina fa parte di una skill per agenti di codifica IA ed è scritta per gli agenti, non per gli esseri umani. Per la documentazione Base44 leggibile dagli umani, consulta la documentazione per sviluppatori.

Modulo Auth

Autenticazione utente, registrazione e gestione della sessione tramite base44.auth.

Tipi TypeScript

Interfaccia 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; // Custom schema fields
}

Interfaccia LoginResponse

interface LoginResponse {
  access_token: string;  // JWT token
  user: User;           // Complete user object
}

Interfacce dei parametri

RegisterParams

interface RegisterParams {
  email: string;                    // Required
  password: string;                 // Required
  turnstile_token?: string | null;  // Optional: Cloudflare Turnstile for bot protection
  referral_code?: string | null;    // Optional: Referral code
}

VerifyOtpParams

interface VerifyOtpParams {
  email: string;     // User's email
  otpCode: string;   // OTP code from email
}

ResetPasswordParams

interface ResetPasswordParams {
  resetToken: string;   // Token from password reset email
  newPassword: string;  // New password to set
}

ChangePasswordParams

interface ChangePasswordParams {
  userId: string;          // User ID
  currentPassword: string; // Current password for verification
  newPassword: string;     // New password to set
}

Tipo Provider

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

Metodi

Interfaccia del modulo

interface AuthModule {
  // User Info
  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;

  // Token Management
  setToken(token: string, saveToStorage?: boolean): void;

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

  // User Management
  inviteUser(userEmail: string, role: string): Promise<any>;

  // Password Management
  resetPasswordRequest(email: string): Promise<any>;
  resetPassword(params: ResetPasswordParams): Promise<any>;
  changePassword(params: ChangePasswordParams): Promise<any>;
}

Tabella di riferimento dei metodi

Metodo	Parametri	Tipo di ritorno	Descrizione
`register()`	`params: RegisterParams`	`Promise<any>`	Crea un nuovo account utente
`loginViaEmailPassword()`	`email: string, password: string, turnstileToken?: string`	`Promise<LoginResponse>`	Autentica con email/password
`loginWithProvider()`	`provider: Provider, fromUrl?: string`	`void`	Avvia il flusso di login OAuth. Provider: `'google'` (default), `'microsoft'`, `'facebook'` (abilita nelle impostazioni dell’app)
`me()`	Nessuno	`Promise<User>`	Ottieni l’utente autenticato corrente
`updateMe()`	`data: Partial<User>`	`Promise<User>`	Aggiorna il profilo dell’utente corrente
`logout()`	`redirectUrl?: string`	`void`	Reindirizza al logout lato server (cancella i cookie HTTP-only e la sessione), poi a redirectUrl o all’URL corrente
`redirectToLogin()`	`nextUrl: string`	`void`	⚠️ Evita - Preferisci un’interfaccia di login personalizzata con `loginViaEmailPassword()` o `loginWithProvider()`
`isAuthenticated()`	Nessuno	`Promise<boolean>`	Controlla se l’utente è loggato
`setToken()`	`token: string, saveToStorage?: boolean`	`void`	Imposta manualmente il token di autenticazione
`inviteUser()`	`userEmail: string, role: string`	`Promise<any>`	Invia email di invito
`verifyOtp()`	`params: VerifyOtpParams`	`Promise<any>`	Verifica il codice OTP
`resendOtp()`	`email: string`	`Promise<any>`	Reinvia il codice OTP
`resetPasswordRequest()`	`email: string`	`Promise<any>`	Richiedi il reset della password
`resetPassword()`	`params: ResetPasswordParams`	`Promise<any>`	Reimposta la password con il token
`changePassword()`	`params: ChangePasswordParams`	`Promise<any>`	Cambia la password dell’utente

Esempi

Registrazione di un nuovo utente (flusso completo)

La registrazione richiede la verifica dell’email prima del login. Flusso completo:

Registrazione - Crea l’account utente
Email di verifica inviata - L’utente riceve un codice OTP
Verifica OTP - L’utente inserisce il codice per verificare l’email
Login - L’utente può ora accedere

try {
  // Step 1: Register the user
  await base44.auth.register({
    email: "user@example.com",
    password: "securePassword123",
    referral_code: "OPTIONAL_CODE",    // optional
    turnstile_token: "CAPTCHA_TOKEN"   // optional, for bot protection
  });
  console.log('Registration successful. Check email for OTP code.');

  // Step 2: User receives email with OTP code (e.g., "123456")

  // Step 3: Verify the OTP code
  await base44.auth.verifyOtp({
    email: "user@example.com",
    otpCode: "123456"  // code from verification email
  });
  console.log('Email verified successfully.');

  // Step 4: Now the user can log in
  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);
  // Handle specific errors (see Error Handling section)
}

Importante: gli utenti non possono accedere finché non completano la verifica OTP. Tentare di chiamare loginViaEmailPassword prima della verifica fallirà.

try {
  const response = await base44.auth.loginViaEmailPassword(
    "user@example.com",
    "password123",
    turnstileToken  // optional: for bot protection
  );

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

  // JWT is automatically stored for subsequent requests

} 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.');
  }
}

Provider supportati: 'google' (abilitato di default), 'microsoft' e 'facebook'. Abilita Microsoft o Facebook nelle impostazioni di autenticazione della tua app prima di usarli.

// Redirect to Google OAuth
base44.auth.loginWithProvider('google');

// Redirect to Google OAuth and return to current page after
base44.auth.loginWithProvider('google', window.location.href);

// Microsoft or Facebook (enable in app settings first)
base44.auth.loginWithProvider('microsoft');
base44.auth.loginWithProvider('facebook', '/dashboard');

Ottenere l’utente corrente

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 expired or invalid - navigate to your custom login page
    navigate('/login');
  }
}

Aggiornare il profilo utente

try {
  const updatedUser = await base44.auth.updateMe({
    full_name: "John Doe",
    // Custom schema fields can be updated here
    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');
  }
}

Controllare lo stato di autenticazione

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

  if (isLoggedIn) {
    // Show authenticated UI
    console.log('User is authenticated');
  } else {
    // Show login button
    console.log('User is not authenticated');
  }

} catch (error) {
  console.error('Failed to check authentication:', error.message);
  // On error, treat as not authenticated
}

Logout

Logout reindirizza l’utente all’endpoint di logout lato server (/api/apps/auth/logout) per cancellare i cookie HTTP-only e la sessione, poi reindirizza all’URL fornito (o alla pagina corrente se omesso). Richiede un ambiente browser.

// Logout: clears session via server, then redirects to current page
base44.auth.logout();

// Logout and redirect to goodbye page after
base44.auth.logout("/goodbye");

// Logout and redirect to homepage
base44.auth.logout("/");

Pattern di route protetta

// Using a navigation function (e.g., React Router's useNavigate, Next.js router)
async function requireAuth(navigate) {
  try {
    const user = await base44.auth.me();

    if (!user) {
      // Navigate to your custom login page
      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;
  }
}

// Usage in your app
async function loadProtectedPage(navigate) {
  const user = await requireAuth(navigate);
  if (!user) {
    // Will navigate to login
    return;
  }

  // Continue with authenticated logic
  console.log('Welcome,', user.full_name);
}

Impostare il token di autenticazione

// SECURITY WARNING: Never hardcode tokens or expose them in client code
// Tokens should only be received from secure authentication flows

// Set token and save to localStorage (default)
base44.auth.setToken(receivedToken);

// Set token without saving to localStorage (temporary session)
base44.auth.setToken(receivedToken, false);

// Verify token was set
try {
  const isAuthenticated = await base44.auth.isAuthenticated();
  if (!isAuthenticated) {
    console.error('Token validation failed');
  }
} catch (error) {
  console.error('Failed to set token:', error.message);
}

Invitare un utente all’applicazione

try {
  // Note: Typically requires admin privileges
  const response = await base44.auth.inviteUser(
    "newuser@example.com",
    "user"  // or "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');
  }
}

Verifica OTP

try {
  // Verify OTP code sent to user's email
  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.');
  }
}

// Resend OTP if needed
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.');
  }
}

Flusso di reset della password

// Step 1: Request password reset
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.');
  }
  // Note: For security, don't reveal if email exists
}

// Step 2: Reset password with token from email
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');
  }
}

Cambiare la password

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');
  }
}

Gestione degli errori

Scenari di errore comuni

Il modulo auth può generare vari errori. Ecco gli scenari comuni e come gestirli:

Errori di autenticazione (401/403)

try {
  const user = await base44.auth.me();
} catch (error) {
  if (error.status === 401) {
    // Token expired or invalid - navigate to your custom login page
    navigate('/login');
  } else if (error.status === 403) {
    // Email not verified or insufficient permissions
    console.error('Access denied:', error.message);
  }
}

Errori di validazione (400/422)

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

Limiti di frequenza (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.');
    // Show countdown or disable button temporarily
  }
}

Gestore di errori generico

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.';
  }
}

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

Provider di autenticazione

Configura i provider di autenticazione nella dashboard della tua app:

Provider disponibili

Integrati (tutti i piani):

Email/Password - Predefinito, sempre abilitato
Google - Autenticazione OAuth
Microsoft - Autenticazione OAuth
Facebook - Autenticazione OAuth

Provider SSO (piano Elite):

Okta
Azure AD
GitHub

Usare i provider OAuth

Google – abilitato di default.
Microsoft – abilita nelle impostazioni di autenticazione della tua app prima dell’uso.
Facebook – abilita nelle impostazioni di autenticazione della tua app prima dell’uso.

// Initiate OAuth login flow
base44.auth.loginWithProvider('google');

// Return to specific page after authentication
base44.auth.loginWithProvider('microsoft', '/dashboard');

// Supported values: 'google', 'microsoft', 'facebook'

Disponibilità per ambiente

Ambiente	Disponibilità	Note
Frontend	✅ Sì	Tutti i metodi disponibili
Funzioni backend	✅ Sì	Usa `createClientFromRequest(req)` per un client autenticato
Ruolo di servizio	❌ No	I metodi auth non sono disponibili nel contesto del ruolo di servizio

Uso nel frontend

// Standard browser usage
const user = await base44.auth.me();

Uso nelle funzioni backend

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

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

  // Get user from request context
  const user = await base44.auth.me();

  // User operations here...
  return Response.json({ user });
});

Visibilità dell’app

Controlla chi può accedere alla tua app nelle impostazioni dell’app:

App pubbliche

Nessun login richiesto per l’accesso di base
Gli utenti possono visualizzare i contenuti pubblici senza autenticazione
Gli utenti autenticati ottengono funzionalità/dati aggiuntivi

App private

Login richiesto per accedere a qualsiasi contenuto
Gli utenti non autenticati vengono reindirizzati automaticamente al login
Tutti i contenuti sono protetti di default

Limitazioni

Opzioni di interfaccia di autenticazione

Consigliato: costruisci un’interfaccia di login/registrazione personalizzata usando loginViaEmailPassword() e loginWithProvider() per un controllo completo sull’esperienza utente e sul branding
Alternativa: redirectToLogin() usa le pagine di autenticazione ospitate da Base44 con personalizzazione limitata

redirectToLogin() mostra sia le opzioni di login sia quelle di registrazione nella stessa pagina
Nessun metodo separato redirectToSignup()
Gli utenti possono passare tra login/registrazione nella pagina ospitata
⚠️ Nota: preferisci costruire un’interfaccia di login personalizzata per una migliore esperienza utente

Requisiti della password

Lunghezza minima e requisiti di complessità applicati
I requisiti non sono esposti tramite API
Errori di validazione restituiti quando i requisiti non sono soddisfatti

Limiti di frequenza

Le richieste OTP sono soggette a limiti di frequenza per prevenire abusi
Le richieste di reset della password sono soggette a limiti di frequenza
I tentativi di login possono essere soggetti a limiti di frequenza con la protezione Turnstile

Gestione del token

I JWT vengono memorizzati automaticamente in localStorage di default
Scadenza e refresh del token non esposti nell’API
Chiama me() o isAuthenticated() per verificare la validità del token

Best practice

1. Gestisci sempre gli errori

try {
  await base44.auth.loginViaEmailPassword(email, password);
} catch (error) {
  // Always handle authentication errors
  console.error('Login failed:', error.message);
}

2. Verifica l’autenticazione prima di azioni protette

const user = await requireAuth();
if (!user) return; // Will redirect to login
// Proceed with authenticated action

3. Usa la type safety 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. Non codificare in modo fisso le credenziali

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

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

5. Fornisci feedback all’utente

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

6. Gestisci con eleganza la scadenza del token

try {
  const user = await base44.auth.me();
} catch (error) {
  if (error.status === 401) {
    // Clear local state and navigate to login
    localStorage.clear();
    navigate('/login');
  }
}

// ✅ RECOMMENDED - Custom login form with direct methods
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');
};

// ❌ AVOID - Redirecting to hosted login page
// base44.auth.redirectToLogin(window.location.href);

Questa pagina è stata tradotta utilizzando l’IA. Per informazioni più accurate e aggiornate, consulta la versione inglese.

​Modulo Auth

​Contenuti

​Tipi TypeScript

​Interfaccia User

​Interfaccia LoginResponse

​Interfacce dei parametri

​RegisterParams

​VerifyOtpParams

​ResetPasswordParams

​ChangePasswordParams

​Tipo Provider

​Metodi

​Interfaccia del modulo

​Tabella di riferimento dei metodi

​Esempi

​Registrazione di un nuovo utente (flusso completo)

​Login con email/password

​Login con provider OAuth

​Ottenere l’utente corrente

​Aggiornare il profilo utente

​Controllare lo stato di autenticazione

​Logout

​Pattern di route protetta

​Impostare il token di autenticazione

​Invitare un utente all’applicazione

​Verifica OTP

​Flusso di reset della password

​Cambiare la password

​Gestione degli errori

​Scenari di errore comuni

​Errori di autenticazione (401/403)

​Errori di validazione (400/422)

​Limiti di frequenza (429)

​Gestore di errori generico

​Provider di autenticazione

​Provider disponibili

​Usare i provider OAuth

​Disponibilità per ambiente

​Uso nel frontend

​Uso nelle funzioni backend

​Visibilità dell’app

​App pubbliche

​App private

​Limitazioni

​Opzioni di interfaccia di autenticazione

​Login ospitato (tramite redirectToLogin)

​Requisiti della password

​Limiti di frequenza

​Gestione del token

​Best practice

​1. Gestisci sempre gli errori

​2. Verifica l’autenticazione prima di azioni protette

​3. Usa la type safety con TypeScript

​4. Non codificare in modo fisso le credenziali

​5. Fornisci feedback all’utente

​6. Gestisci con eleganza la scadenza del token

​7. Costruisci un’interfaccia di login personalizzata (consigliato)

Modulo Auth

Contenuti

Tipi TypeScript

Interfaccia User

Interfaccia LoginResponse

Interfacce dei parametri

RegisterParams

VerifyOtpParams

ResetPasswordParams

ChangePasswordParams

Tipo Provider

Metodi

Interfaccia del modulo

Tabella di riferimento dei metodi

Esempi

Registrazione di un nuovo utente (flusso completo)

Login con email/password

Login con provider OAuth

Ottenere l’utente corrente

Aggiornare il profilo utente

Controllare lo stato di autenticazione

Logout

Pattern di route protetta

Impostare il token di autenticazione

Invitare un utente all’applicazione

Verifica OTP

Flusso di reset della password

Cambiare la password

Gestione degli errori

Scenari di errore comuni

Errori di autenticazione (401/403)

Errori di validazione (400/422)

Limiti di frequenza (429)

Gestore di errori generico

Provider di autenticazione

Provider disponibili

Usare i provider OAuth

Disponibilità per ambiente

Uso nel frontend

Uso nelle funzioni backend

Visibilità dell’app

App pubbliche

App private

Limitazioni

Opzioni di interfaccia di autenticazione

Login ospitato (tramite redirectToLogin)

Requisiti della password

Limiti di frequenza

Gestione del token

Best practice

1. Gestisci sempre gli errori

2. Verifica l’autenticazione prima di azioni protette

3. Usa la type safety con TypeScript

4. Non codificare in modo fisso le credenziali

5. Fornisci feedback all’utente

6. Gestisci con eleganza la scadenza del token

7. Costruisci un’interfaccia di login personalizzata (consigliato)