> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modulo Auth

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

<Warning>
  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](/developers).
</Warning>

# Modulo Auth

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

## Contenuti

* [Tipi TypeScript](#tipi-typescript)
* [Metodi](#metodi)
* [Esempi](#esempi)
* [Gestione degli errori](#gestione-degli-errori)
* [Provider di autenticazione](#provider-di-autenticazione)
* [Disponibilità per ambiente](#disponibilità-per-ambiente)
* [Visibilità dell'app](#visibilità-dellapp)
* [Limitazioni](#limitazioni)

***

## Tipi TypeScript

### Interfaccia User

```typescript theme={null}
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

```typescript theme={null}
interface LoginResponse {
  access_token: string;  // JWT token
  user: User;           // Complete user object
}
```

### Interfacce dei parametri

#### RegisterParams

```typescript theme={null}
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

```typescript theme={null}
interface VerifyOtpParams {
  email: string;     // User's email
  otpCode: string;   // OTP code from email
}
```

#### ResetPasswordParams

```typescript theme={null}
interface ResetPasswordParams {
  resetToken: string;   // Token from password reset email
  newPassword: string;  // New password to set
}
```

#### ChangePasswordParams

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

### Tipo Provider

```typescript theme={null}
type Provider = 'google' | 'microsoft' | 'facebook';
```

***

## Metodi

### Interfaccia del modulo

```typescript theme={null}
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:

1. **Registrazione** - Crea l'account utente
2. **Email di verifica inviata** - L'utente riceve un codice OTP
3. **Verifica OTP** - L'utente inserisce il codice per verificare l'email
4. **Login** - L'utente può ora accedere

```javascript theme={null}
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à.

### Login con email/password

```javascript theme={null}
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.');
  }
}
```

### Login con provider OAuth

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

```javascript theme={null}
// 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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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.

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
// 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

```javascript theme={null}
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)

```javascript theme={null}
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)

```javascript theme={null}
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)

```javascript theme={null}
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

```javascript theme={null}
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.

```javascript theme={null}
// 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

```javascript theme={null}
// Standard browser usage
const user = await base44.auth.me();
```

### Uso nelle funzioni backend

```javascript theme={null}
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

### Login ospitato (tramite redirectToLogin)

* `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

```javascript theme={null}
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

```javascript theme={null}
const user = await requireAuth();
if (!user) return; // Will redirect to login
// Proceed with authenticated action
```

### 3. Usa la type safety con TypeScript

```typescript theme={null}
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

```javascript theme={null}
// ❌ BAD
base44.auth.setToken("hardcoded-token-here");

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

### 5. Fornisci feedback all'utente

```javascript theme={null}
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

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

### 7. Costruisci un'interfaccia di login personalizzata (consigliato)

```javascript theme={null}
// ✅ 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);
```

<Note>Questa pagina è stata tradotta utilizzando l'IA. Per informazioni più accurate e aggiornate, consulta la [versione inglese](/). </Note>