Overview

Supersaas provides a robust and flexible authentication system built on top of nuxt-auth-utils, created by Atinux (creator of Nuxt). The system supports multiple authentication methods to accommodate different user preferences and security requirements.

Supported Authentication Methods

1. Email/Password Authentication
2. Magic Link Authentication
3. Passkey (WebAuthn) Authentication
4. Phone Number Authentication (SMS OTP)
5. Social Authentication (Google, GitHub, Discord)

Core Authentication Components

Auth Composable

The useAuth composable (app/composables/useAuth.ts) serves as the central authentication service, providing methods for:

• User registration
• Email/password login
• Password reset
• Email verification
• Error handling with toast notifications

const {
  login,
  logout,
  register,
  forgotPassword,
  resetPassword,
  resendVerification,
} = useAuth();

Session Management

User sessions are managed through useUserSession composable provided by nuxt-auth-utils. The session includes:

• User authentication state
• User profile information
• Session persistence
• Auto-refresh capabilities

Example usage:

const { user, loggedIn, fetch: refreshSession } = useUserSession();

Auth Middleware

The authentication system includes middleware to protect routes and handle authentication state:

// Example of using auth middleware
definePageMeta({
  middleware: ["auth"],
});

User Account Management

The useUserAccount composable provides functionality for managing user account settings:

const { updateUser, updatePassword, loading } = useUserAccount();

Features:

• Update user profile information
• Change password
• Form validation using Zod schemas
• Loading states for async operations
• Toast notifications for success/error feedback

Team Management

The useTeam composable handles team-related authentication and management:

const { currentTeam, isTeamOwner, teams } = useTeam();

Features:

• Team membership management
• Team ownership verification
• Team slug-based routing
• Team data fetching and caching

Error Handling

The authentication system includes comprehensive error handling:

• Form validation errors using Zod schemas
• API error responses with descriptive messages
• Toast notifications for user feedback
• Special handling for unverified email accounts
• OAuth provider-specific error messages

Security Features

1. Password Hashing
2. Email Verification
3. Session Management
4. Rate Limiting
5. CSRF Protection
6. Secure Cookie Handling
7. OAuth State Validation

Best Practices

1. Always use the provided composables (useAuth, useUserAccount, useTeam) instead of direct API calls
2. Implement proper form validation using the provided Zod schemas
3. Handle loading states appropriately
4. Use toast notifications for user feedback
5. Implement proper error handling
6. Use middleware for protected routes
7. Follow the established authentication flows for each method

Configuration

The authentication system can be configured through:

1. Environment Variables
2. Runtime Config
3. OAuth Provider Settings
4. Email Templates
5. Session Settings