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

# Authentication Guide

> Learn how to register, login, and manage your TopFormBuilder account securely.

## Registration

TopFormBuilder offers two ways to create your account:

### Method 1: Email & Password Registration

1. **Visit Registration Page**
   * Go to [app.topformbuilder.com/register](https://app.topformbuilder.com/register)
2. **Fill Registration Form**
   * **Name**: Your full name (required, max 255 characters)
   * **Email**: Valid email address (required, must be unique)
   * **Password**: Minimum 8 characters (required)
   * **Confirm Password**: Must match password (required)
3. **Submit Registration**
   * Click **"Register"** button
   * Form validates your input
   * Account is created if validation passes
4. **Email Verification** (if enabled)
   * Check your email inbox
   * Click verification link in email
   * Your email is now verified
5. **Automatic Setup** Upon successful registration, TopFormBuilder automatically creates:
   * **Personal Organization**: Named `Your Name's Organization`
   * **Default Workspace**: Named `My Workspace`
   * **Organization Member Record**: You as Owner role
   * **Workspace Member Record**: You as Admin role
6. **Redirect to Dashboard**
   * You're automatically logged in
   * Redirected to your dashboard at `/dashboard`

### Method 2: Google OAuth Registration

1. **Visit Registration Page**
   * Go to [app.topformbuilder.com/register](https://app.topformbuilder.com/register)
2. **Click "Continue with Google"**
   * Look for Google button with colorful logo
   * Below the divider "Or continue with"
3. **Google Authorization**
   * Redirected to Google login page
   * Select your Google account
   * Grant permissions to TopFormBuilder
   * Redirected back to TopFormBuilder
4. **Account Creation** If this is your first time:
   * New user account is created with Google details
   * **Email**: From your Google account
   * **Name**: From your Google profile
   * **Avatar**: Your Google profile picture
   * **Email Verified**: Automatically verified
   * **Provider**: Set to "google"
   * **Provider ID**: Your Google user ID
   * **Password**: NULL (OAuth users don't need passwords)
5. **Automatic Setup** (Same as email registration)
   * Personal Organization created
   * Default Workspace created
   * Member records created
6. **Success**
   * Logged in automatically
   * Welcome message: "Welcome back, \[Your Name]!"
   * Redirected to `/dashboard`

### Important Notes About Google OAuth

**Security Behavior:**

* If email already exists with **password-based account**: Login blocked with error message
* If email already exists with **Google OAuth**: Login successful
* If email already exists with **different OAuth provider**: Login blocked (e.g., if you used Facebook before)

**Why This Matters:**

* Prevents unauthorized access via OAuth if you registered with password
* You can link OAuth accounts from Settings after password login

## Login

### Email & Password Login

1. **Visit Login Page**
   * Go to [app.topformbuilder.com/login](https://app.topformbuilder.com/login)
2. **Enter Credentials**
   * **Email**: Your registered email
   * **Password**: Your account password
   * **Remember Me** (optional): Stay logged in for 2 weeks
3. **Submit**
   * Click **"Log in"** button
   * Validates credentials
   * Redirects to dashboard if successful
4. **Errors**
   * Invalid credentials: "These credentials do not match our records"
   * Account not verified: "Please verify your email address"
   * Too many attempts: Rate limited for security

### Google OAuth Login

1. **Visit Login Page**
   * Go to [app.topformbuilder.com/login](https://app.topformbuilder.com/login)
2. **Click "Continue with Google"**
   * Below the divider "Or continue with"
3. **Google Authorization**
   * Select your Google account
   * Grant permissions
   * Redirected back to TopFormBuilder
4. **Success**
   * Logged in automatically
   * Redirected to intended page or dashboard

### Session Management

* **Session Lifetime**: 120 minutes (2 hours) by default
* **Remember Me**: Extends session for 2 weeks
* **Session Storage**: Database (secure session management)
* **CSRF Protection**: Enabled on all forms
* **Same Site Cookie**: Lax mode for security

## Password Reset

Forgot your password? Reset it easily:

1. **Visit Forgot Password Page**
   * Go to [app.topformbuilder.com/forgot-password](https://app.topformbuilder.com/forgot-password)
   * Or click "Forgot your password?" on login page
2. **Enter Email**
   * Type your registered email address
   * Click **"Email Password Reset Link"**
3. **Check Email**
   * Email sent to your inbox
   * Subject: "Reset Password Notification"
   * Contains secure reset link (expires in 60 minutes)
4. **Click Reset Link**
   * Opens reset password page
   * Token is validated automatically
5. **Set New Password**
   * **Email**: Pre-filled (read-only)
   * **Password**: New password (min 8 characters)
   * **Confirm Password**: Repeat new password
6. **Submit**
   * Click **"Reset Password"**
   * Password updated in database (bcrypt hashed)
   * Redirected to login page
   * Login with new password

### Rate Limiting

Password reset requests are rate limited:

* **Limit**: 6 requests per minute per email
* **Purpose**: Prevent abuse and spam
* **Error**: "Please wait before retrying"

## Password Confirmation

For sensitive operations, you may need to confirm your password:

1. **Triggered Actions**
   * Changing email address
   * Deleting account
   * Updating payment methods
   * Other critical operations
2. **Confirmation Page**
   * Shows at `/confirm-password`
   * Message: "This is a secure area. Please confirm your password."
3. **Enter Password**
   * Type your current password
   * Click **"Confirm"**
4. **Validation**
   * Password verified against database
   * Access granted if correct
   * Returns to original intended action
5. **Session Valid For**
   * 3 hours after confirmation
   * No need to re-confirm in this window

## Email Verification

TopFormBuilder supports email verification (optional feature):

### When Enabled

1. **After Registration**
   * Email sent automatically
   * Subject: "Verify Email Address"
   * Contains signed verification link
2. **Verification Notice**
   * Shown when accessing protected pages
   * Message: "Thanks for signing up! Before getting started, please verify your email address."
   * **Resend** button available
3. **Click Verification Link**
   * Opens `/verify-email/{id}/{hash}` route
   * Link is signed and has timestamp
   * Validates signature and expiration
4. **Success**
   * Email marked as verified
   * `email_verified_at` timestamp set
   * Redirected to dashboard
   * Full access granted

### Resend Verification

If you didn't receive the email:

1. **Click "Resend Verification Email"**
   * On verification notice page
   * Rate limited: 6 requests per minute
2. **New Email Sent**
   * Fresh verification link
   * Valid for 60 minutes
   * Success message: "A new verification link has been sent"

## Logout

Safely logout from your account:

1. **Click Profile Menu**
   * Top right corner of any page
   * Shows your name and avatar
2. **Select "Log Out"**
   * Or navigate to `/logout` route
3. **Confirmation**
   * Session destroyed immediately
   * All login tokens invalidated
   * Redirected to homepage or login
4. **Security**
   * Logout requires POST request (CSRF protected)
   * Cannot logout via GET URL
   * Prevents cross-site logout attacks

## Account Security

### Password Requirements

TopFormBuilder enforces strong passwords:

* **Minimum Length**: 8 characters
* **Recommended**: 12+ characters with mix of:
  * Uppercase letters (A-Z)
  * Lowercase letters (a-z)
  * Numbers (0-9)
  * Special characters (!@#\$%^&\*)

### Password Hashing

* **Algorithm**: Bcrypt with automatic salt
* **Rounds**: 12 rounds (configurable)
* **Security**: Passwords never stored in plain text
* **Standard**: PHP `password_hash()` with `PASSWORD_BCRYPT`

## OAuth Provider Details

### Supported Providers

Currently supported:

* **Google OAuth** - Fully implemented
* **GitHub** - Coming soon
* **Microsoft** - Coming soon
* **Facebook** - Coming soon

### Google OAuth Configuration

Your app uses Google OAuth with these settings:

* **Provider**: Google
* **Scopes**: Email, Profile, OpenID
* **Redirect URI**: `{APP_URL}/auth/google/callback`
* **Driver**: Laravel Socialite

### OAuth User Data Stored

When you login with Google, we store:

* **provider**: "google"
* **provider\_id**: Your Google user ID
* **name**: From Google profile
* **email**: From Google account
* **avatar**: Google profile picture URL
* **email\_verified\_at**: Set to current time (auto-verified)

### Linking OAuth Accounts

Future feature (not yet implemented):

* Link Google account to existing password account
* Unlink OAuth providers
* Manage connected accounts from Profile → Connected Accounts

## Multi-Organization Access

Your user account can access multiple organizations:

1. **Personal Organization**
   * Created automatically on signup
   * You are the owner
   * Cannot be deleted
   * Marked as `is_personal: true`
2. **Team Organizations**
   * Join via invitation
   * Different roles: Owner, Admin, Member
   * Access based on role permissions
3. **Organization Switching**
   * Switch between organizations in UI
   * All workspaces under selected organization
   * Settings and members vary per organization

## Troubleshooting

### "Email already taken"

**Problem**: Email address already registered

**Solution**:

* Use different email address, OR
* Login with existing account, OR
* Reset password if you forgot it

### "Invalid credentials"

**Problem**: Wrong email or password

**Solution**:

* Check email spelling and case
* Check caps lock for password
* Try password reset if unsure

### "Too many login attempts"

**Problem**: Rate limited after failed attempts

**Solution**:

* Wait 1 minute
* Try again with correct credentials
* Contact support if locked out

### "Google login says 'email already exists'"

**Problem**: Account exists with password-based registration

**Solution**:

* Login with email and password instead
* After login, link Google account from Settings
* Cannot directly login with Google if registered with password

### "Verification email not received"

**Problem**: Email didn't arrive

**Solution**:

* Check spam/junk folder
* Check email address spelling
* Click "Resend verification email"
* Wait 2-3 minutes for delivery
* Contact support if still not received

### "Reset link expired"

**Problem**: Waited too long to reset password

**Solution**:

* Request new reset link
* Reset links expire after 60 minutes
* Use link within 1 hour of request

## API Authentication

For developers using the API:

### Sanctum Token Authentication

1. **Get API Token**
   * Go to Profile → API Tokens
   * Click "Create New Token"
   * Name your token (e.g., "Mobile App", "Integration")
   * Copy token (shown only once!)
2. **Use Token in Requests**

   ```bash theme={null}
   curl https://app.topformbuilder.com/api/forms \
     -H "Authorization: Bearer YOUR_TOKEN_HERE"
   ```
3. **Token Permissions**
   * Full access to your account
   * Same permissions as your user role
   * Can be revoked anytime
4. **Token Security**
   * Never share tokens publicly
   * Rotate tokens regularly
   * Revoke compromised tokens immediately
   * Use different tokens for different apps

### API Token Management

* **View Tokens**: See all active tokens
* **Revoke Token**: Delete specific token
* **Last Used**: See when token was last used
* **Permissions**: Currently all or nothing (granular permissions coming soon)

## Privacy & Data

### What We Store

* Email address (for login)
* Name (for display)
* Password hash (bcrypt, never plain text)
* OAuth provider info (if using Google login)
* Avatar URL (if using Google login)
* Login timestamps
* Session data (temporary)
* User preferences (locale, theme, etc.)

### What We Don't Store

* Plain text passwords (always hashed)
* Credit card details (handled by Stripe/Paddle)
* OAuth tokens (except refresh tokens for integrations)

### GDPR Rights

You have the right to:

* **Export Your Data**: Download all your data
* **Delete Your Account**: Request account deletion
* **Update Information**: Change email, name, etc.
* **Revoke Consent**: Withdraw consent anytime

See [Privacy & GDPR Guide](./privacy-gdpr.md) for more details.

***

[**Need help? Contact contact@topformbuilder.com**](mailto:contact@topformbuilder.com)