Esta página faz parte de uma habilidade de agente de código IA e é escrita para agentes, não para humanos. Para a documentação legível por humanos da Base44, veja a documentação para desenvolvedores.

Módulo Auth

Autenticação de usuário, registro e gerenciamento de sessão via base44.auth.

Conteúdo

Tipos TypeScript
Métodos
Exemplos
Tratamento de erros
Provedores de autenticação
Disponibilidade de ambiente
Visibilidade do aplicativo
Limitações

Tipos TypeScript

Interface 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
}

Interface LoginResponse

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

Interfaces de parâmetros

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

Métodos

Interface do módulo

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

Tabela de referência de métodos

Método	Parâmetros	Tipo de retorno	Descrição
`register()`	`params: RegisterParams`	`Promise<any>`	Cria nova conta de usuário
`loginViaEmailPassword()`	`email: string, password: string, turnstileToken?: string`	`Promise<LoginResponse>`	Autentica com e-mail/senha
`loginWithProvider()`	`provider: Provider, fromUrl?: string`	`void`	Inicia fluxo de login OAuth. Provedores: `'google'` (padrão), `'microsoft'`, `'facebook'` (ative nas configurações do aplicativo)
`me()`	Nenhum	`Promise<User>`	Obtém usuário atualmente autenticado
`updateMe()`	`data: Partial<User>`	`Promise<User>`	Atualiza perfil do usuário atual
`logout()`	`redirectUrl?: string`	`void`	Redireciona para logout do lado do servidor (limpa cookies HTTP-only e sessão), depois para redirectUrl ou URL atual
`redirectToLogin()`	`nextUrl: string`	`void`	⚠️ Evite - Prefira UI de login personalizada com `loginViaEmailPassword()` ou `loginWithProvider()`
`isAuthenticated()`	Nenhum	`Promise<boolean>`	Verifica se o usuário está logado
`setToken()`	`token: string, saveToStorage?: boolean`	`void`	Define manualmente o token de autenticação
`inviteUser()`	`userEmail: string, role: string`	`Promise<any>`	Envia e-mail de convite
`verifyOtp()`	`params: VerifyOtpParams`	`Promise<any>`	Verifica código OTP
`resendOtp()`	`email: string`	`Promise<any>`	Reenvia código OTP
`resetPasswordRequest()`	`email: string`	`Promise<any>`	Solicita redefinição de senha
`resetPassword()`	`params: ResetPasswordParams`	`Promise<any>`	Redefine senha com token
`changePassword()`	`params: ChangePasswordParams`	`Promise<any>`	Altera senha do usuário

Exemplos

Registrar novo usuário (fluxo completo)

O registro requer verificação de e-mail antes do login. Fluxo completo:

Registrar - Cria a conta do usuário
E-mail de verificação enviado - O usuário recebe um código OTP
Verificar OTP - O usuário insere o código para verificar o e-mail
Login - O usuário agora pode fazer login

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: Os usuários não podem fazer login até que concluam a verificação OTP. Tentar chamar loginViaEmailPassword antes da verificação falhará.

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

Provedores suportados: 'google' (ativado por padrão), 'microsoft' e 'facebook'. Ative Microsoft ou Facebook nas configurações de autenticação do seu aplicativo antes de usá-los.

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

Obter usuário atual

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

Atualizar perfil de usuário

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

Verificar status de autenticação

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

O logout redireciona o usuário para o endpoint de logout do lado do servidor (/api/apps/auth/logout) para limpar cookies HTTP-only e a sessão, depois redireciona para a URL fornecida (ou a página atual se omitida). Requer um ambiente de navegador.

// 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("/");

Padrão de rota protegida

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

Definir token de autenticação

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

Convidar usuário para o aplicativo

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

Fluxo de redefinição de senha

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

Alterar senha

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

Tratamento de erros

Cenários de erro comuns

O módulo auth pode lançar vários erros. Aqui estão cenários comuns e como tratá-los:

Erros de autenticação (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);
  }
}

Erros de validação (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);
  }
}

Limitação de taxa (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
  }
}

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

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

Provedores de autenticação

Configure provedores de autenticação no painel do seu aplicativo:

Provedores disponíveis

Integrados (todos os planos):

E-mail/senha - Padrão, sempre ativado
Google - Autenticação OAuth
Microsoft - Autenticação OAuth
Facebook - Autenticação OAuth

Provedores SSO (plano Elite):

Okta
Azure AD
GitHub

Usando provedores OAuth

Google – ativado por padrão.
Microsoft – ative nas configurações de autenticação do seu aplicativo antes de usar.
Facebook – ative nas configurações de autenticação do seu aplicativo antes de usar.

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

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

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

Disponibilidade de ambiente

Ambiente	Disponibilidade	Notas
Frontend	✅ Sim	Todos os métodos disponíveis
Funções de backend	✅ Sim	Use `createClientFromRequest(req)` para cliente autenticado
Service Role	❌ Não	Métodos de autenticação não disponíveis no contexto service role

Uso no frontend

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

Uso em funções de 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 });
});

Visibilidade do aplicativo

Controle quem pode acessar seu aplicativo nas configurações do aplicativo:

Aplicativos públicos

Nenhum login necessário para acesso básico
Os usuários podem visualizar conteúdo público sem autenticação
Usuários autenticados obtêm recursos/dados adicionais

Aplicativos privados

Login necessário para acessar qualquer conteúdo
Usuários não autenticados são automaticamente redirecionados para login
Todo o conteúdo é protegido por padrão

Limitações

Opções de UI de autenticação

Recomendado: Construa UI de login/cadastro personalizada usando loginViaEmailPassword() e loginWithProvider() para controle total sobre experiência do usuário e branding
Alternativa: redirectToLogin() usa páginas de autenticação hospedadas pela Base44 com personalização limitada

redirectToLogin() mostra opções de login e cadastro na mesma página
Nenhum método redirectToSignup() separado
Os usuários podem alternar entre login/cadastro na página hospedada
⚠️ Nota: Prefira construir UI de login personalizada para melhor experiência do usuário

Requisitos de senha

Comprimento mínimo e requisitos de complexidade impostos
Requisitos não expostos via API
Erros de validação retornados quando requisitos não são atendidos

Limitação de taxa

Solicitações OTP são limitadas para prevenir abuso
Solicitações de redefinição de senha são limitadas
Tentativas de login podem ser limitadas com proteção Turnstile

Gerenciamento de tokens

JWTs são armazenados automaticamente no localStorage por padrão
Expiração e atualização de tokens não expostos na API
Chame me() ou isAuthenticated() para verificar validade do token

Melhores práticas

1. Sempre trate erros

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

2. Verifique autenticação antes de ações protegidas

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

3. Use segurança de tipos com 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. Não hardcode credenciais

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

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

5. Forneça feedback ao usuário

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

6. Trate a expiração de token graciosamente

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

Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a versão em inglês.

​Módulo Auth

​Conteúdo

​Tipos TypeScript

​Interface User

​Interface LoginResponse

​Interfaces de parâmetros

​RegisterParams

​VerifyOtpParams

​ResetPasswordParams

​ChangePasswordParams

​Tipo Provider

​Métodos

​Interface do módulo

​Tabela de referência de métodos

​Exemplos

​Registrar novo usuário (fluxo completo)

​Login com e-mail/senha

​Login com provedor OAuth

​Obter usuário atual

​Atualizar perfil de usuário

​Verificar status de autenticação

​Logout

​Padrão de rota protegida

​Definir token de autenticação

​Convidar usuário para o aplicativo

​Verificação OTP

​Fluxo de redefinição de senha

​Alterar senha

​Tratamento de erros

​Cenários de erro comuns

​Erros de autenticação (401/403)

​Erros de validação (400/422)

​Limitação de taxa (429)

​Manipulador de erros genérico

​Provedores de autenticação

​Provedores disponíveis

​Usando provedores OAuth

​Disponibilidade de ambiente

​Uso no frontend

​Uso em funções de backend

​Visibilidade do aplicativo

​Aplicativos públicos

​Aplicativos privados

​Limitações

​Opções de UI de autenticação

​Login hospedado (via redirectToLogin)

​Requisitos de senha

​Limitação de taxa

​Gerenciamento de tokens

​Melhores práticas

​1. Sempre trate erros

​2. Verifique autenticação antes de ações protegidas

​3. Use segurança de tipos com TypeScript

​4. Não hardcode credenciais

​5. Forneça feedback ao usuário

​6. Trate a expiração de token graciosamente

​7. Construa UI de login personalizada (recomendado)

Módulo Auth

Conteúdo

Tipos TypeScript

Interface User

Interface LoginResponse

Interfaces de parâmetros

RegisterParams

VerifyOtpParams

ResetPasswordParams

ChangePasswordParams

Tipo Provider

Métodos

Interface do módulo

Tabela de referência de métodos

Exemplos

Registrar novo usuário (fluxo completo)

Login com e-mail/senha

Login com provedor OAuth

Obter usuário atual

Atualizar perfil de usuário

Verificar status de autenticação

Logout

Padrão de rota protegida

Definir token de autenticação

Convidar usuário para o aplicativo

Verificação OTP

Fluxo de redefinição de senha

Alterar senha

Tratamento de erros

Cenários de erro comuns

Erros de autenticação (401/403)

Erros de validação (400/422)

Limitação de taxa (429)

Manipulador de erros genérico

Provedores de autenticação

Provedores disponíveis

Usando provedores OAuth

Disponibilidade de ambiente

Uso no frontend

Uso em funções de backend

Visibilidade do aplicativo

Aplicativos públicos

Aplicativos privados

Limitações

Opções de UI de autenticação

Login hospedado (via redirectToLogin)

Requisitos de senha

Limitação de taxa

Gerenciamento de tokens

Melhores práticas

1. Sempre trate erros

2. Verifique autenticação antes de ações protegidas

3. Use segurança de tipos com TypeScript

4. Não hardcode credenciais

5. Forneça feedback ao usuário

6. Trate a expiração de token graciosamente

7. Construa UI de login personalizada (recomendado)