# Forgot Password

## OpenAlgo Password Reset System

### Overview

OpenAlgo provides a comprehensive dual-mode password reset system that allows users to recover their accounts through either:

1. **TOTP (Time-based One-Time Password)** authentication
2. **Email verification** (requires SMTP configuration)

This system is designed with security best practices and provides fallback options for different scenarios.

### Table of Contents

* System Architecture
* Authentication Methods
* Setup Requirements
* User Flow
* Configuration Guide
* Security Features
* Troubleshooting
* API Endpoints
* Rate Limiting

### System Architecture

The password reset system follows a secure token-based approach with multiple verification methods:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   User Request  │    │  Method Selection │    │  Verification   │
│                 │───▶│                  │───▶│                 │
│ Enter Email     │    │ TOTP or Email    │    │ Code/Link Check │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                          │
                       ┌─────────────────┐               │
                       │  Password Reset │◀──────────────┘
                       │                 │
                       │ New Password    │
                       └─────────────────┘
```

### Authentication Methods

#### 1. TOTP Authentication (Recommended)

**Advantages:**

* Works offline
* No external dependencies
* Immediate verification
* Always available

**Requirements:**

* User must have TOTP configured
* Authenticator app (Google Authenticator, Authy, etc.)

**Flow:**

1. User enters email address
2. User selects "TOTP Authentication"
3. User enters TOTP code from authenticator app
4. System validates code and allows password reset

#### 2. Email Verification

**Advantages:**

* User-friendly
* No additional app required
* Secure email delivery

**Requirements:**

* SMTP configuration must be completed
* User has access to their email

**Flow:**

1. User enters email address
2. User selects "Email Verification"
3. System sends reset link to user's email
4. User clicks link and resets password

### Setup Requirements

#### TOTP Setup (Always Available)

TOTP is automatically configured during account creation. Each user gets:

* Unique TOTP secret key
* QR code for easy setup
* Backup secret for manual entry

#### SMTP Configuration (Required for Email Reset)

**Personal Gmail Configuration:**

```
SMTP Server: smtp.gmail.com
Port: 587 (STARTTLS) or 465 (SSL/TLS)
Username: your-email@gmail.com
Password: [App Password - NOT regular password]
HELO Hostname: smtp.gmail.com
Use TLS: Yes
```

**Gmail Workspace Configuration:**

```
SMTP Server: smtp-relay.gmail.com
Port: 465 (SSL/TLS)
Username: your-email@yourdomain.com
Password: [App Password]
HELO Hostname: smtp.gmail.com
Use TLS: Yes
```

**App Password Setup for Gmail:**

1. Go to Google Account Settings
2. Navigate to Security → 2-Step Verification
3. Select "App passwords"
4. Generate a new app password for "Mail"
5. Use this password in SMTP configuration

### User Flow

#### Password Reset Process

1. **Initial Request**
   * User visits `/auth/reset-password`
   * Enters email address
   * System validates email format (client-side and server-side)
2. **Method Selection**
   * System presents two verification options:
     * TOTP Authentication (always available)
     * Email Verification (if SMTP configured)
   * User selects preferred method
3. **TOTP Verification Path**
   * User enters TOTP code from authenticator app
   * System validates code against user's TOTP secret
   * If valid, generates secure reset token
   * User proceeds to password reset form
4. **Email Verification Path**
   * System generates secure reset token
   * Sends password reset email with secure link
   * User clicks link in email
   * System validates token and shows password reset form
5. **Password Reset**
   * User enters new password
   * System validates password meets requirements:
     * Minimum 8 characters
     * At least 1 uppercase letter (A-Z)
     * At least 1 lowercase letter (a-z)
     * At least 1 number (0-9)
     * At least 1 special character (@#$%^&\*)
   * Password is hashed and stored securely
   * All reset tokens are invalidated

### Configuration Guide

#### SMTP Configuration

Access SMTP settings at `/auth/change` → "SMTP Configuration" tab:

1. **Server Settings**
   * Enter SMTP server hostname
   * Set appropriate port (587 for STARTTLS, 465 for SSL/TLS)
   * Configure HELO hostname
2. **Authentication**
   * Enter username (usually email address)
   * Enter App Password (not regular password for Gmail)
   * Set from email address
3. **Security**
   * Enable TLS/SSL encryption
   * Test configuration before saving
4. **Testing**
   * Use "Send Test" to verify configuration
   * Use "Debug" for detailed connection diagnostics

#### TOTP Configuration

Access TOTP settings at `/auth/change` → "TOTP Authentication" tab:

1. **QR Code Setup**
   * Scan QR code with authenticator app
   * Or manually enter the secret key
2. **Supported Apps**
   * Google Authenticator
   * Authy
   * Microsoft Authenticator
   * 1Password
   * Bitwarden
3. **Backup**
   * Save secret key in secure location
   * Test TOTP generation before relying on it

### Security Features

#### Token Security

* **Cryptographically secure tokens**: 32-byte URL-safe tokens
* **Session-based validation**: Tokens stored in server-side sessions
* **Single-use tokens**: Tokens invalidated after successful use
* **Time-limited validity**: Email tokens expire with session
* **Secure transmission**: HTTPS-only token delivery

#### Anti-Enumeration Protection

* **Consistent responses**: Same response regardless of email existence
* **Information leakage prevention**: No indication if email is registered
* **Rate limiting**: Prevents brute force attacks

#### Additional Security Measures

* **CSRF protection**: All forms protected with CSRF tokens
* **Input validation**: Email format and password strength validation
* **Secure password hashing**: Bcrypt with proper salt rounds
* **Session security**: Secure session cookie configuration

### Troubleshooting

#### Common SMTP Issues

**Gmail Authentication Failed**

```
Error: SMTP Authentication failed
Solution: Use App Password instead of regular password
Steps: Google Account → Security → 2-Step Verification → App passwords
```

**Gmail Workspace Relay Denied**

```
Error: Mail relay denied
Solution 1: Register server IP in Google Admin Console
Solution 2: Switch to personal Gmail settings (smtp.gmail.com:587)
```

**Connection Timeout**

```
Error: Connection timeout
Check: Firewall blocking SMTP ports (587, 465)
Check: Network connectivity to SMTP server
```

**SSL/TLS Errors**

```
Error: SSL handshake failed
Solution: Verify port configuration (587=STARTTLS, 465=SSL/TLS)
Check: Certificate validation settings
```

#### Common TOTP Issues

**Invalid TOTP Code**

```
Issue: Code not accepted
Check: Time synchronization on device
Check: Code not expired (30-second window)
Solution: Manually sync time in authenticator app
```

**Lost Authenticator Device**

```
Issue: Cannot generate TOTP codes
Solution: Use backup secret key to reconfigure
Fallback: Contact administrator for manual reset
```

#### Email Delivery Issues

**Email Not Received**

```
Check: Spam/junk folder
Check: Email address typos
Check: SMTP server logs
Verify: Test email functionality works
```

**Reset Link Expired**

```
Issue: "Invalid or expired reset link"
Cause: Session expired or link already used
Solution: Request new password reset
```

### ⚠️ Nuclear Option: Complete Database Reset

#### When All Else Fails

If you cannot access your OpenAlgo account through any method (TOTP broken, email not working, lost credentials), \
\
1\)stop openalgo application \
2\)Locate the file openalgo.db from the db folder\
3\)delete the openalgo.db database file form the /db folder \
4\)restart the openalgo application\
5\)Start signup with openalgo fresh\
6\)Ensure Gmail SMTP Settings or TOTP Authenticator is Configured

<figure><img src="/files/md9RDi6T8y979db2aO5f" alt=""><figcaption></figcaption></figure>

#### What You Will Lose

⚠️ **WARNING: This action is irreversible and will permanently delete:**

* **User accounts and passwords**
* **All trading logs and history**
* **API access logs and analytics**
* **Strategy configurations and backtests**
* **SMTP/email settings**
* **Rate limiting history**
* **System settings and preferences**
* **Custom configurations**

#### Prevention for Future

To avoid needing database reset:

1. **Save TOTP Secret Key**: Store authenticator backup codes securely
2. **Configure SMTP Early**: Set up email recovery before you need it
3. **Document Credentials**: Keep encrypted record of important settings
4. **Regular Backups**: Schedule automatic database backups
5. **Test Recovery**: Periodically test password reset functionality

#### Alternative Recovery Methods

Before resorting to database reset, try these:

1. **TOTP Secret Recovery**: If you saved the original secret key, re-add to authenticator
2. **Database Editing**: Advanced users can directly edit SQLite database to reset passwords
3. **Python Script Recovery**: Create custom script to reset user password in database
4. **Backup Restoration**: If you have recent database backup, restore it instead

### Rate Limiting

The password reset system implements rate limiting to prevent abuse:

#### Configuration

```env
# Login rate limits (applied to reset password as well)
LOGIN_RATE_LIMIT_MIN=5 per minute
LOGIN_RATE_LIMIT_HOUR=25 per hour

# Password reset specific limit
RESET_RATE_LIMIT=15 per hour
```

#### Limits Applied

* **Password reset requests**: 15 per hour per IP
* **SMTP test requests**: Inherits from login limits
* **Failed authentication attempts**: Tracked separately

#### Rate Limit Headers

When rate limited, responses include:

* `X-RateLimit-Limit`: Maximum requests allowed
* `X-RateLimit-Remaining`: Requests remaining in window
* `X-RateLimit-Reset`: Time when limit resets

### Best Practices

#### For Users

1. **TOTP Setup**: Always configure TOTP as primary recovery method
2. **Backup Codes**: Save TOTP secret key securely
3. **Email Security**: Use secure email provider with 2FA
4. **Strong Passwords**: Follow password requirements strictly

####


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openalgo.in/installation-guidelines/getting-started/forgot-password.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.