Chunks — 1. Agency Auth_

✅ Agency Sign Up

# **Sign Up Module**

## **1\. Module Overview**

*   **Module Name:** User Registration/Sign Up
*   **Purpose:** Allow solo photographers, videographers, and agency owners who are not yet registered to create an account and complete onboarding in the system.
*   **Business Goal:** Provide a secure entry point for new users to access the CRM platform and initiate a 14-day free trial

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Unregistered User

Visitor attempting to create an account

Access to the registration form, view terms/privacy policy links

Note: User roles (Solo operator or Studio) within CRM are assigned during the onboarding flow after successful registration

## **3\. User Flow**

**Primary Path - Create Account:**

1.  The user lands on the registration page and selects "Create Account."
2.  User fills mandatory fields (First Name, Last Name, Email, Password)
3.  The system validates all inputs and creates an account
4.  The system sends a verification email to the user (email verification link valid for 7 days)
5.  The user redirects to the onboarding flow.

**Alternative Path - Google Sign Up:**

1.  The user selects "Sign up with Google."
2.  Google authentication flow initiates
3.  User grants permissions in Google OAuth
4.  The system creates an account with Google profile data
5.  The user redirects to the onboarding flow

**Critical Path:** Registration → Validation → Account Creation → Onboarding Redirect

**Referral Page**:

1.  The user can Sign Up using a referral link, showing a different sign-up page. - Refer to [10\. Referral](https://docs.google.com/document/d/19Py56HfYjWkRCRU47Ei-QOhwHT_lcfNPjdlIC6CMYnk/edit?usp=drive_link)

## **4.** **Field Details & Validations**

**Field Name**

**Type**

**Required**

**Validation Rules**

First Name

Text

Yes

Max 50 chars

Last Name

Text

Yes

Max 50 chars

Email address

Email

Yes

\- Not already registered in the system

\- Valid format, unique, no disposable emails  
\- Restricted emails mentioned in this [list](https://docs.google.com/document/d/1lctff12IzxpifIDGm3rmHd2BTE80vnI_38PwYD7MWNI/edit?tab=t.9chj4bpf6vu9#bookmark=id.z54aqfcxz7s5)

Password

Password

Yes

Min 6 - Max 20 chars, 1 uppercase, 1 number, 1 special char, no spaces

Eye Icon Toggle

Icon

Yes

Show/hide password functionality

Create Account

Button

Yes

Always enabled; on click, triggers validation (if applicable), otherwise advances the user to the onboarding flow.

Sign Up with Google

Button

Optional

On click opens the Google sign-up flow and after that advances the user to the onboarding flow

Login

Text (Button)

Optional

Redirects the user to the login screen

reCAPTCHA

Verification

Yes

Implement reCAPTCHA for website security

Terms & Conditions, Privacy Policy, and Terms of Service

Hyperlink

Yes

Functional links to legal pages

## **5\.** **Success Message Handling**

**Validation Scenario**

**Success Message**

On successfully signing up

"Your account has been created successfully."

## **6.** **Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

First Name

Empty submission

"Please enter your first name."

First Name

Length (characters) > 50

"First name cannot exceed 50 characters."

Last Name

Empty submission

"Please enter your last name."

Last Name

Length (characters) > 50

"Last name cannot exceed 50 characters."

Email

Empty email submission

"Please enter your email address."

Email

Invalid format

"Please enter a valid email address."

Email

Same email register

"User with this email already exists."

Email

Disposable email

“Disposable or mock emails are not allowed.”

Password

Empty submission

"Please enter your password."

Password

Weak password (Password validations)

Show only the next missing condition as the user types, updating the message after each requirement is met.  
Requirement:  
\- “Password must be at least 6 characters.”

\- “Password must contain at least one uppercase letter.”

\- “Password must contain at least one number.”

\- “Password must contain at least one special character.”

\- “Password must contain at least one lowercase letter.”

\- “Password cannot exceed 20 characters.”

General

Server/API error

“Something went wrong."

Google Auth

Cancelled flow

“Something went wrong."

Google Auth

Network/API issue

“Something went wrong."

## **7\. Functional Logic**

*   **Account Creation:** The System creates a unique user account with encrypted password storage
*   **Email Uniqueness:** Prevent duplicate registrations using case-insensitive email validation
*   **Trial Initiation:** Automatically activate a 14-day free trial period upon successful sign-up/registration
*   **Google OAuth Integration:** Create an account using Google profile data without a password requirement
*   **Cross-Authentication Prevention:** Google-registered emails cannot be used for manual account creation and vice versa
*   **Session Management:** Initiate user session upon successful sign-up/registration for a seamless onboarding transition
*   **Security Protection:** Implement reCAPTCHA v3 for bot prevention and spam protection

## **8\. Edge Cases**

**Scenario**

**Expected Behavior**

The user refreshes the page during sign-up/registration

Clear all fields, and show a validation error if the attempted submission

Google authentication was cancelled mid-flow

Do not register email, allow retry with both methods

Simultaneous sign-up/registration with the same email

The first successful sign-up/registration wins, second shows a duplicate error "User with this email already exists."

Password visibility toggle during typing

When toggled on, display the password; otherwise, keep the cursor position and show dots to mask the typed content.

Terms/Privacy links in a new tab

Open in a new tab without losing sign-up/registration form data

reCAPTCHA failure

Prevent form submission, show verification error

Session timeout on the sign-up/registration page

Maintain form data until submission attempt

## **9\. Test Cases**

## **Link:** [Pixally Test cases](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=1054361793#gid=1054361793)

## **10\. Acceptance Criteria**

*   **Successful Sign-Up/Registration:** Both manual and Google registration processes create valid user accounts
*   **Field Validation:** All input fields validate according to specified rules with appropriate error messages
*   **Security Implementation:** reCAPTCHA v3 protection prevents automated registrations
*   **Navigation:** All CTAs and hyperlinks function correctly (Create Account, Google Sign Up, Login redirect)
*   **Legal Compliance:** Terms & Conditions, Privacy Policy, and Terms of Service links work properly
*   **Password Security:** Eye toggle successfully shows/hides the password
*   **Trial Activation:** A 14-day free trial automatically initiates upon successful sign-up/registration
*   **Cross-Platform Prevention:** Google-registered emails cannot be used for manual sign-up and vice versa
*   **Onboarding Transition:** Successful registration redirects to the onboarding flow
*   **Error Handling:** Graceful error handling for network issues, API failures, and user cancellations

## **11\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Onboarding Flow

Workflow dependency

Users cannot complete the onboarding after signing up

Login Module

Data dependency

Cannot authenticate registered users

Subscription Module

Data dependency

Cannot use functionalities

Dashboard

Navigation dependency

No post-onboarding destination for users

Agency Profile Settings

Data dependency

User information not reflected in the profile

Email Service

External dependency

Cannot send verification or welcome emails

Google OAuth API

External dependency

The Google sign-up option is unavailable

reCAPTCHA Service

External dependency

No bot protection, potential spam sign-up/registrations

Database

Infrastructure dependency

Cannot store user accounts

## **12\. References**

*   **Figma Design Link:** [](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=4459-347092&t=iP8AGUaWixubhkYv-0)[**Click here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13406-333112&t=i14G6DPzEn8J5SUJ-0)

✅ Post Sign Up

# **Post Sign-Up Flow**

## **Module Overview**

*   **Module Name:** Post Sign-Up Email Verification & Trial Management
*   **Purpose:** Handle email verification, account activation, trial period management, and super admin notifications after successful user registration
*   **Business Goal:** Ensure verified user accounts, manage trial periods, and provide admin oversight of new registrations

## **Core Functionality**

### **1\. Email Verification System**

**Trigger Event:** Immediately after a successful user sign-up/registration with an email ID. (No verification required for Google Sign up)

**Verification Process:**

*   The system generates a unique verification link with a 7-day validity
*   Automated email sent to the registered email address
*   Single-use verification link (expires after first use or 7 days)
*   Users can request the verification link from the portal (Once the user regenerates the verification link, the previous link will expire)
*   Email verification is required before trial activation (purchasing subscription)

### **2\. Account Restriction & Recovery System**

**Account Restriction Conditions:**

*   If the user fails to verify the email within 7 days of registration, then the user account automatically transitions to a restricted status, and a pop-up is displayed informing the user that their account has been blocked. The pop-up will include a “Resend Verification Link” button
*   If the logged-in user has not verified the email, the user will log out of the system.
*   The user cannot log in or access any portal functionality until the email verification is complete.

**Restriction Notification:**

*   A pop-up modal appears when a user attempts to log in
*   Message: "Please verify your email to reactivate your account and continue enjoying our services."
*   The "Resend Verification Link" button is prominently displayed

**Resend Functionality:**

*   The user clicks the "Resend Verification Link" button on the pop-up
*   The system generates a new verification link
*   A new verification email was sent to the user's registered email
*   Upon clicking the verification link, the user will be redirected to the logged-in screen with the message “Your account is verified successfully.”
*   The user remains logged out and restricted until email verification is completed

### **3\. Super Admin Notifications**

**Notification Trigger:** After any user signs up, the Gawd Portal admin (super user) will receive an email notification about the new user's sign-up.

### **4\. Trial Period Management**

**Trial Activation:**

*   The 14-day free trial period begins immediately upon sign-up
*   The 14-day trial countdown starts from the successful sign-up/registration date
*   The system tracks the trial's remaining days

**Trial Limitations:**

*   Payment functionalities like receiving or sending payments are disabled
*   Can not create more than one brand
*   Can not invite team members
*   Third-party service integrations restricted (QuickBooks, Google Calendar, Calendly)
*   All data management features are available

**Trial Validation Logic:**

*   The system checks emails against historical trial usage
*   Validate previous trial periods by email address
*   Prevents multiple trials from the same email address

###

### **5\. Trial Expiration Handling**

**Pre-Expiration Warnings:**

*   Email notifications at 14 days, 7 days, and 3 days left in the trial period
*   Display banner notifications in the dashboard header when there are 14 (Yellow), 7(Blue), and 3 days(light beige) remaining in the trial period. Each notification should include a button that directs users to the subscription section to purchase a plan.
*   Send email notification when the trial period expires (i.e 7, 3, 1 days remaining) - (The client will provide us email templates)
*   Send email notifications after the trial period expires - (The client will provide us with email templates and frequency)
*   In-app notifications with subscription upgrade prompts

**Post-Expiration Actions:**

*   Account transitions to view-only mode
*   Display subscription upgrade prompt with pricing plans
*   Data remains accessible but non-editable (View-only mode)
*   Super Admin (Gawd portal) can reset trial periods (unlimited)

## **Business Rules & Logic**

### **Account Status Workflow:**

1.  **Registered** → Verification email sent, awaiting verification
2.  **Pending Email Verification** → 7-day verification countdown active
3.  **Email Verified** → Trial period remains activated until 14 days
4.  **Trial Active** → Full access (minus payment features and multiple brand creation)
5.  **Trial Expired** → CRM data will be in view-only mode
6.  **User Restricted** → Failed verification, user logged out and cannot access the system until verification

## **Dependencies & Integration Points**

**Module**

**Dependency Type**

**Description**

Email Service Provider

External Service

SMTP configuration for verification emails, email template management system, email delivery tracking

Gawd Portal (Super Admin)

Internal Module

Super admin can reset the trial period for any specific user and also can increase the trial period length  
\- Account status update (new user registrations)

Subscription Management

Internal Module

Trial-to-paid conversion tracking, payment gateway restrictions, subscription plan integration

Admin Dashboard

Internal Module

Display the remaining days of the trial in the heading banner format  
\- 14 days, 7 days and 3 days

QuickBooks Integration

Third-Party Service

Integration controls and restriction management during the trial period

Google Calendar

Third-Party Service

Restriction management during the trial period

Calendly Integration

Third-Party Service

Integration limitations during the trial period

**Test cases :** [**Pixally Test cases - 01.04.25**](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=1977662597#gid=1977662597)

✅ Agency Sign In/Login

# **Sign In Module**

# **1\. Module Overview**

*   **Module Name:** Sign In / User Authentication
*   **Purpose:** Allow studio owners and solo operators who have already signed up for Pixally CRM to securely access the Pixally CRM using their registered email/password or Google authentication.
*   **Business Goal:** Provide secure, user-friendly authentication with multiple login options and robust password recovery

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Agency Admin/Solo operator

Studio/Agency owner or Solo operator with full administrative access

Full access to the agency dashboard and all CRM features

## **3\. User Flow**

### **Normal Sign In Flow:**

1.  The user navigates to the sign-in page.
2.  The user enters an already registered email address and password (with an optional visibility toggle).
3.  The user clicks the "Sign in" button.
4.  The system validates credentials and redirects to the Onboarding (If incompleted) agency dashboard or (2FA- if first-time sign-in refers [here](?tab=t.afhgfg77ifdn) ).
5.  **Two-Factor Authentication**:
    1.  When the user attempts to sign in, after entering valid credentials, the system will detect that 2FA is enabled on their account settings.
    2.  If enabled then the user will be prompted to complete the two-factor authentication step using their enrolled method(s), such as SMS/Email:
    3.  The system will validate the entered OTP.
    4.  Upon successful verification of the two-factor authentication, the user will be redirected to the dashboard.
6.  **Email verification**: The system will check whether email verification is completed or not within 7 days after sign-up.
    1.  If verification is not completed within these 7 days after sign-up, a pop-up will appear, prompting the user to resend the email verification link.
    2.  Until the user verifies their email, they will not be able to perform any actions within the application. All data will be displayed in view-only mode, restricting any modifications.
    3.  However, if the user has already completed setup two-factor authentication using their email address, the email will be automatically marked as verified, and a separate email verification step will not be required.
7.  **Trial Period Check:** The system checks whether the 14-day trial period associated with the user’s account has ended, counting from the date of sign-up.
    1.  If the trial period is over, a pop-up will appear to notify the user that the 14-day trial period has ended. The pop-up will prompt the user to subscribe based on available subscription options.
    2.  Once the trial period has ended, the user will no longer be able to perform any actions; all modules will be set to view-only mode.
8.  **Valid Subscription Check**:
    1.  For existing subscribers, the system will check their current subscription payment status. If a user is on a monthly or yearly plan and their payment fails after three unsuccessful attempts, they will be redirected to the subscription payment page upon signing in.

### **Google Sign In Flow:**

1.  The user navigates to the sign-in page.
2.  The user clicks the "Continue with Google" button.
3.  The user completes Google OAuth authentication.
4.  The system validates Google credentials and redirects to the agency dashboard.

### **Alternative Paths:**

*   **Forgot Password:** User clicks "Forgot Password?" → Password reset flow
*   **New User:** User clicks "Get Started" → Sign Up/Registration flow

**Critical Path:** Successful authentication → Agency Dashboard

## **4.** **Field Details & Validations**

**Field Name**

**Type**

**Required**

**Validation Rules**

Email Address

Email

Yes

\- Valid email format ([user@example.com](mailto:user@example.com))

\- No spaces allowed

\- Must be registered in the system

\- Case insensitive

Password

Password

Yes

\- Must match the sign-up/registered password

\- No spaces allowed

\- Min 6 and Max 20 characters (as per sign-up validation)

\- After 5+ incorrect attempts, restrict submission for one hour for the particular email and display a relevant error message

Eye Icon Toggle

Toggle

Optional

\- Shows/hides password text

\- Default state: password hidden

Forgot password

Text (Button)

Optional

\- On click redirects the user to the forgot password screen

Sign In Button

CTA

Mandatory

\- Validate all fields before submission and display the relevant error message (if applicable)

\- Triggers the authentication process and opens the two-factor authentication (if applicable)

\- Redirect to the Dashboard (if no validation error)

Continue with Google

OAuth CTA

Optional

\- Initiates Google OAuth flow and on successful login, redirects the user to the dashboard

Get Started

Text (Button)

Optional

On click opens the sign-up screen

Normal Auth

User registered via Gmail → logs in via Normal auth (any password)

NA

“Invalid Credentials. Please try again.”

Google Auth

User registered via Normal auth→ logs in via Google (same email)

NA

“Google authentication failed.”

## **5\. Field Details (2FA)**

### **OTP Verification Pop-Up (If 2FA is Activated)**

**Field Name**

**Type**

**Required**

**Validation Rules**

OTP Input (6 boxes)

Text

Yes

\- Single digit per box (0-9)

\- Total 6 characters,

\- Auto-advance between fields

\- Display “-” in the blank box

Resend code

Button

Optional

\- Allows the user to request new OTP

\- Resend is available only after 60 seconds have passed since the last resend

\- 3 times resend allowed

Verify

Button

Yes

\- Validates OTP

\- Disabled until all 6 boxes are filled

\- On successful validation redirects to the dashboard

## **6\.** **Success Message Handling**

**Validation Scenario**

**Success Message**

On successfully signing in

"You’ve logged in successfully."

##

## **7\.** **Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

Email

Empty submission

"Please enter your email address."

Email

Not registered

“Invalid Credentials. Please try again.”

Email

Invalid format

"Please enter a valid email address."

Password

Empty submission

"Please enter your password."

Authentication

Invalid credentials, email/password, or either email or password

"Invalid Credentials. Please try again."

Password

Locked after 5 failed login attempts

"Your account has been locked due to multiple failed login attempts. Please try again after one hour."

OTP Input

Invalid/Expired OTP entered

"Incorrect OTP. Please try again."

OTP Input

5 wrong OTP attempts

"You have entered an incorrect OTP multiple times. Please try again after one hour."

OTP Input

Resend limit reached (5 times)

"Resend limit exceeded. Please try again after one hour."

Google Auth

User registered via email/password → logs in via Google (same email)

“Google authentication failed.”

Normal Auth

User registered via Gmail → logs in via email/password (any password)

“Invalid Credentials. Please try again.”

General

Server error

"Something went wrong."

**8\. Functional Logic**

*   **Authentication Method Validation:** The system checks the registration method (normal vs Google) and displays the relevant error message
*   **Failed Attempt Counter:** The system monitors consecutive failed login attempts for each email address. If a user enters an incorrect password 5+ times in a row, their account will be locked for 1 hour, preventing further password entry during this period
*   **Account Lockout:** Locked accounts automatically unlock after exactly 1 hour from lockout time
*   **Password Visibility:** The eye icon toggle allows users to show/hide password text for convenience
*   **Case Insensitive Email:** Email validation treats uppercase and lowercase as identical
*   **OTP Generation**: The System generates a 6-digit OTP (0-9)
*   **OTP Verification**: The System verifies the entered OTP with the last generated valid OTP
*   **OTP Expiration**: OTP code expires after 2 minutes
*   **Attempt Limits**: Users have 5 OTP attempts; after that, they’re restricted for 1 hour.
*   **Resend Logic**: A New OTP can be requested after 60 seconds of the last resend, a maximum of 5 resend attempts, and on the resend, the previous OTP will be invalid/expired
*   **Resend limit**: If the user resends the OTP 5 times, they will be restricted for 1 hour
*   **Auto-advance**: OTP input fields automatically advance to the next field upon character entry
*   **Verify Button State**: OTP Verify button remains disabled until all 6 input boxes are filled

## **9\. Edge Cases**

**Scenario**

**Expected Behavior**

Users with an incomplete onboarding attempt log in

Redirect to the last onboarding step where the user left

(handled by the onboarding module)

The user cancels the onboarding in between the steps

Redirect to the last onboarding step where the user left

Multiple rapid login attempts

Each failed attempt counts toward the 5-attempt limit

The user closes the browser during two-factor authentication

On the next login, the 2FA pop-up comes

The user registered with Google tries a normal login

Show error directing to Google login (Continue with Google)

The user who registered normally tries the Google login

Show error directing to normal authentication

Subscription not purchased even after the free 14-day trial period over

The user’s account will be restricted, with a pop-up displayed prompting the user to purchase a subscription plan

##

## **10\. Test Cases**

*   **Link:** [**Pixally Test cases**](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=1054361793#gid=1054361793)

## **11\. Acceptance Criteria**

*   Users can successfully log in with their registered email and password
*   Users can toggle password visibility using the eye icon
*   Users can sign in using Google authentication
*   The system enforces an authentication method based on the registration type
*   Failed login attempts are tracked, and the account locks after 5 failures
*   Locked accounts automatically unlock after 1 hour
*   Appropriate error messages display for all validation scenarios
*   Successful log-in redirects to the Two-factor authentication (if activated,) otherwise redirects to the agency dashboard
*   The system successfully sends OTP codes via the already set up method (Email/SMS)
*   OTP input fields automatically focus next field upon character entry
*   Lockout Enforcement
    *   Users are locked out for 1 hour if they resend the OTP 5 times
    *   Users are locked out for 1 hour if they enter the wrong OTP 5 times
*   Users can navigate to the sign-up page via the "Get Started" link
*   Users can access password recovery via the "Forgot Password?" link
*   The system prevents cross-method authentication (Google users can't use normal login and vice versa)
*   ReCAPTCHA v3 runs invisibly in the background for spam prevention

**12\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Sign Up

Data dependency

Cannot validate registered users

Subscription Module

Free trial management

Cannot validate the user for subscription required after 14 days

Two Factor Auth

Check if enabled or not

Can not open two-factor authentication

Agency Dashboard

Navigation dependency

Cannot redirect after successful login

Onboarding

Flow dependency

Cannot handle incomplete onboarding scenarios

Forgot Password

Navigation dependency

Password recovery unavailable

Google OAuth Service

External dependency

Google authentication unavailable

User Database

Data dependency

Cannot authenticate any users

Email Service Provider

External Integration

Email OTP delivery fails; users cannot complete email-based 2FA

SMS Service Provider

External Integration

SMS OTP delivery fails; users cannot complete SMS-based 2FA

## **13\. References**

*   **Figma Link:** [**Click Here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13406-300879&t=ksWBAHb4a3i1V5rH-0)

✅ Forgot Password

# **Password Recovery Module**

## **1\. Module Overview**

*   **Module Name:** User Authentication - Password Recovery
*   **Purpose:** Provide users with a secure multi-step process to reset forgotten passwords via email verification
*   **Business Goal:** Enable account recovery while maintaining security standards and reducing support tickets

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Agency Owner

System administrator

Access to the password recovery process

Note: All registered users have equal access to password recovery functionality

## **3\. User Flow**

### **Main Password Recovery Flow:**

1.  The user clicks the "Forgot Password?" link on the login screen
2.  The user enters the registered email address on the “Forgot your password?” screen
3.  The system verifies whether the user is signed up via Google.
    1.  If yes: Display the relevant error message
4.  The system validates the email and sends a recovery link
5.  The user receives a confirmation screen that the recovery link has been sent
6.  The user clicks the recovery link in the email
7.  The user enters and confirms the new password
8.  The system updates the password
9.  The user will be redirected to the login screen

**Critical Path:** Email submission → Email delivery → Link validation → Password reset → Login redirect

## **4\. Field Details & Validations**

### **Step 1: Forgot your password?**

**Field Name**

**Type**

**Required**

**Validation Rules**

Email Address

Email

Yes

\- Valid email format

\- Must be registered in the system

\- Google sign-up users are not allowed to reset their passwords

Send Request

Button

Yes

\- On click, validates the email field and displays the relevant error message (if applicable)

\- Send the password reset link to the user's email if all validations are successfully passed

Return to login

Text (clickable)

Optional

On click, it redirects the user to the login screen

### **Step 2: Recovery link sent!**

**Field Name**

**Type**

**Required**

**Validation Rules**

Help text

Text

Yes

Display the help text and email address to which the password reset link has been sent

Return to login

Button

Yes

On click, it redirects the user to the login screen

### **Step 3: Set a new password**

**Field Name**

**Type**

**Required**

**Validation Rules**

New Password

Password

Yes

Min 6 - Max 20 chars, 1 uppercase, 1 number, 1 special char, no spaces

Repeat Password

Password

Yes

Must match the new password exactly

Confirm New Password

Button

Yes

\- Validate password fields before submission and display the relevant error message (if applicable)

\- When clicked (with no validation errors), it saves the new password for the user and redirects to the login screen

## **5\. Error Message Handling**

### **Step 1: Forgot your password?**

**Field**

**Validation Scenario**

**Error Message**

Email Address

Empty submission

"Please enter your email address."

Email Address

Invalid format

"Please enter a valid email address."

Email Address

Unregistered email

“Invalid Credentials. Please try again.”

Email Address

Sign in using Google and try to reset your password

“Password reset isn’t available for Google-linked accounts.”

Email Address

Trying to resend the password again within 15 minutes of the last request

"Reset link already sent. Please try again in a few minutes."

General

Server error

"Something went wrong."

###

###

### **Step 2: Set new password**

**Field**

**Validation Scenario**

**Error Message**

New Password

Empty

"Please enter a new password."

New Password

Weak Password

Show only the next missing condition as the user types, updating the message after each requirement is met.  
Requirement:  
\- “Password must be at least 6 characters.”

\- “Password must contain at least one uppercase letter.”

\- “Password must contain at least one number.”

\- “Password must contain at least one special character.”

\- “Password must contain at least one lowercase letter.”

Repeat Password

Empty

"Please re-enter your new password."

New Password and Repeat Password

Mismatch

"The passwords you entered do not match. Please try again."

New Password and Repeat Password

Same as the old password

“Your new password can not match your old one. Please choose a different password.”

General

Invalid/expired token

"Something went wrong."

## **6\. Functional Logic**

### **Progressive Password Validation**

*   In the new password display, only the next missing requirement is displayed as the user types
*   Update validation messages dynamically after each requirement is met

### **Email Rate Limiting**

*   Limit password reset requests to one per email address every 15 minutes
*   Previous recovery links are invalidated when a new request is made.

### **Session Management**

*   Once the password is changed, all active sessions will be logged out everywhere, requiring a fresh login.
*   The user must log in again with new credentials

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

The user clicks the expired reset link

Show an error message: “This reset link has expired. Please request a new one.”

Multiple reset requests for the same email

Only the latest link remains valid; the previous links are invalidated

The user navigates away during password entry

Must restart the process from the start to reset the password

## **8\. Test Cases**

*   **Link:**

## **9\. Acceptance Criteria**

*   Users can initiate password recovery from the sign-in/login screen via the "Forgot Password?" link
*   The system validates email addresses and provides appropriate error messages for invalid/unregistered/Google-authenticated emails
*   Reset password links expire exactly 10 minutes after generation
*   Password validation shows progressive, real-time feedback as the user types
*   A successful password reset invalidates all existing user sessions
*   Users are redirected to the login screen after a successful password change
*   Rate limiting prevents abuse with a 15-minute cooldown per email address
*   ReCAPTCHA v3 runs invisibly in the background for spam prevention

## **10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Sign Up Module

Data dependency

Cannot validate registered email addresses

Email Service

Integration dependency

Cannot send recovery links to users

User Database

Data dependency

Cannot authenticate email addresses or store new passwords

Session Management

Functional dependency

Cannot invalidate existing sessions after password change

## **11\. References**

*   **Figma Design Link:** [Forgot Password](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13406-316947&t=LIV1L3Fuhc2LzmIB-0)

✅ Agency Onboarding

# **Agency Onboarding Module**

**1\. Module Overview**

*   **Module Name**: Agency Onboarding Module
*   **Purpose**: After the user signs up multi-step onboarding process is used to collect the agency owner's business information, CRM history, and system preferences
*   **Business Goal**: Gather comprehensive business information and ensure a smooth user transition into the Pixally CRM platform

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

Agency Owner

New user completing onboarding

Access to the onboarding flow, data input, and theme selection

## **3\. User Flow**

1.  **User completes sign-up** → Redirected to Onboarding Step 1
2.  **Step 1: Business Information** → Collect business type, name, phone, and referral source
3.  **Step 2: Website Details** → Capture the company website URL
4.  **Step 3: Additional Questions** → CRM switching status, business duration, revenue (optional)
5.  **Step 4: Theme Selection** → Choose a light/dark theme preference
6.  **Step 5: Search Introduction** → Demonstrate global search functionality (Cmd+K)
7.  **Completion** → Redirect to Agency Dashboard

**Critical Path**: Sign up → All mandatory fields completed in Steps 1-3 → Theme selection → Dashboard access

**4\. Field Details & Validations**

### **Step 1: Tell us about your business**

**Field Name**

**Type**

**Required**

**Validation Rules**

Solo operator/Studio

Radio Button

Yes

Solo Operator OR Studio (with tooltip)

Business Name

Text

Yes

\- Min 2 - Max 100 characters  
\- Can have the alphabet, numbers, and special characters

\- Space is allowed

Business Type

Dropdown

Yes

Single selection from predefined options  
Options:

\- Photography, Videography, Content Creation, Photo/Video

Phone Number

Phone

Yes

\- Country code dropdown

\- Only numbers

\- Valid number

\- Max 15 digits

How did you hear about us

Dropdown

Yes

Single selection from predefined options  
Options:  
\- Search Engine  
\- Facebook  
\- Instagram  
\- YouTube

\- Word of Mouth  
\- Wayward North

\- A.I. Chatbot (ChatGPT, etc)

\- Other

Next Button

Button

Yes

Validates form and navigate to Step 2

###

### **Step 2: Your Company Website**

**Field Name**

**Type**

**Required**

**Validation Rules**

Company Website

URL Input

Yes

Valid URL format

Back Button

Button

Yes

Returns to Step 1 with data preservation

Next Button

Button

Yes

Validates form and navigates to Step 3

### **Step 3: Additional Questions**

**Field Name**

**Type**

**Required**

**Validation Rules**

Are you switching from another CRM

Toggle

Yes

Yes/No (triggers conditional fields)

Previous CRM

Dropdown

Conditional

Required if CRM switching = Yes

How do you imagine transitioning to Pixally

Text area

No

Display if switching from another CRM toggle = Yes,  
Min 10 - Max 250 characters

How long have you had your business

Button Group

No

Single selection from predefined options.  
Options:  
\- Haven’t started  
\- Under a year  
\- 1-2 years

\- 3-4 years

\- 5+ years

What’s your average annual business revenue

Button Group

No

Single selection from predefined options  
Options:

\- Less than $50K  
\- $50K-$100K  
\- $100K-$250K  
\- $250K-$500K  
\- $500K-$1M  
\- Over $1M

Back Button

Button

Yes

Returns to Step 2 with data preservation

Next Button

Button

Yes

Validates form and navigates to Step 4

### **Step 4: Theme Selection**

**Field Name**

**Type**

**Required**

**Validation Rules**

Theme Choice

Card Selection

Yes

\- Light Theme OR Dark Theme

\- The selected theme will be saved for the logged-in user and will remain applied even after the user logs out and logs back in

Continue Button

Button

Yes

Applies the theme and navigates to Step 5

### **Step 5: Search Introduction**

**Field Name**

**Type**

**Required**

**Validation Rules**

Search Demo

Interactive Demo

No

View only demonstrates Cmd+K functionality

Continue Button

Button

Yes

Completes onboarding and redirects to Dashboard

## **5.** **Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

Are you a solo operator or a studio

No selection

“Please select a business model.”

Business Name

Empty

“Please enter your business name.”

Business Name

< 2 chars

“Business name must contain at least 2 characters.”

Business Name

\> 100 chars

“Business name cannot exceed 100 characters.”

Business Type

No selection

“Please select a business type.”

Phone Number

Empty

“Please enter your phone number.”

Phone Number

Invalid format

“Please enter a valid phone number.”

Referral Source

No selection

“Please select a referral source.”

Company Website

Empty

“Please enter your company website.”

Company Website

Invalid URL

“Please enter a valid website URL.”

Are you switching from another CRM

Empty when switching = Yes

“Please select the previous CRM option.”

## **6\. Functional Logic**

*   **Navigation Control**: Next/Back buttons manage step progression with data validation. The "Next" button will remain enabled. If validations fail, display relevant errors.
*   **Data Preservation Logic**: Back navigation maintains all form data across steps
*   **Conditional Field Display**: CRM switching toggle shows/hides Previous CRM (Are you switching from another CRM?) and Transition fields (How do you imagine transitioning to Pixally?)
*   **URL Validation**: Accepts valid URL formats
*   **Theme Application**: The selected theme is applied immediately to all subsequent screens. The user’s theme preference is saved and will remain applied even after logging out and logging back in.
    *   Note: Until the user reaches the "Choose experience you want to have" step during onboarding, the application's theme (light or dark) will follow the browser/system preference by default. Once the user selects a theme during onboarding, that choice will override the browser preference for all future sessions.
*   **Business model (Solo/studio)** \- If the agency is a solo operator, a warning banner will be displayed whenever a new lead arrives for a date on which the solo operator already has a booked job, prompting the user to check availability.

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

The user refreshes the page mid-onboarding

All data will be reset, but the user will remain on the current step.

User closes tab/browser in between onboarding

On the next sign-in/login, the user is redirected to the onboarding step from where the user last left

The session expires upon completion

Auto-save draft, require re-authentication, resume from current step

The user toggles CRM, switching multiple times

Preserve previously entered CRM data when re-enabled

## **8\. Test Cases:**

## **Link:** [**Pixally Test cases**](https://docs.google.com/spreadsheets/d/1RNM15mQt_Ax15liD7LeQZTvi_N01Hax4yZXSNIcN2dI/edit?gid=1054361793#gid=1054361793)

## **9\. Acceptance Criteria**

*   **Complete Data Flow**: The user can progress through all steps without data loss during back navigation
*   **Validation Coverage**: All mandatory fields validate properly with appropriate error messages
*   **Conditional Logic**: CRM switching toggle correctly shows/hides dependent fields
*   **Theme Integration**: The selected theme applies to the dashboard after onboarding completion, and the selected theme is applied immediately to all subsequent screens. The user’s theme preference is saved and will remain applied even after logging out and logging back in.
*   **Session Handling**: Incomplete onboarding blocks dashboard access until completion
*   **Error Recovery**: Clear error messages guide the user to correct invalid inputs
*   **Progress Tracking**: Step indicator accurately reflects current progress
*   **Data Persistence**: Back navigation preserves all entered data across steps
*   **Business Model Configuration**: Solo operator selection is properly stored and triggers downstream business logic
*   **Availability Conflict System**: Solo operator business model enables warning banner functionality for double-booked leads
*   **Warning Banner Activation**: System validates solo operator status before displaying availability conflict warnings

**10\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Sign Up Module

User Verification

Cannot validate user session, onboarding access blocked

User Profile Database

Data storage

Cannot save onboarding data permanently

Dashboard Module

Navigation target

Cannot redirect after completion

Global Search

Feature introduction

The search tutorial cannot be demonstrated

Theme Engine

UI customization

The selected theme cannot be applied

##

## **11\. References**

*   **Figma Design**: [](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13090-147894&t=BVOqObyXYtFRkhLT-0)[**Click here**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13406-333147&t=ksWBAHb4a3i1V5rH-0)

✅ 2FA

# **Two-Factor Authentication (2FA) Setup**

## **1\. Module Overview**

*   **Module Name:** Two-Factor Authentication (2FA) Setup & Login Verification
*   **Purpose:** Allow users to optionally enable 2FA using Email, SMS, or both, and verify their identity at login when 2FA is active. Additionally, ensure that users' contact methods (email and phone) are verified at login to maintain account security.
*   **Business Goal:** Provide an optional additional layer of security for user accounts while offering flexibility to opt-in or skip at first login, and guarantee that contact methods on file are genuinely owned by the user.
*   **Scope:** This FRD covers:
    *   First-login 2FA setup pop-up flow (single-method selection, one-time only)
    *   Login verification flow when 2FA is enabled (single-method or dual-method OTP delivery)
    *   Login-time verification of email and phone when those contacts are not yet verified
*   **Note:** 2FA management from the Settings page (enabling, disabling, adding methods, changing phone number, verifying contact details via Settings) is covered in the separate **Global Settings – 2-Step Verification** FRD.

## **2\. User Roles & Permissions**

**Role**

**Description**

**Key Permissions**

User

Authenticated regular user

Access 2FA setup flow; choose Email/SMS; skip setup at first login; complete OTP verification

Google User

User authenticated via Google OAuth

Same as User, but email is pre-verified via OAuth; can only set up **SMS** 2FA

Agency Admin

Agency administrator with elevated privileges

Same as User; can modify personal phone number without affecting agency master data

## **3\. User Flow**

### **3.0. Skip 2FA (First Login)**

*   User logs in successfully for the first time
*   2FA setup pop-up appears with Email/SMS options + "Skip" button
*   User clicks "Skip"
*   User proceeds directly to the dashboard
*   The pop-up will **not** reappear at subsequent logins; if the user wants to set up 2FA later, they must do so from Settings → 2-Step Verification

**Critical Path:** Optional security enhancement that can be bypassed once; no repeating reminder.

### **3.1. First-Login 2FA Setup — SMS Flow (Regular User)**

*   2FA setup pop-up appears with Email/SMS options
*   User selects "Set up using SMS"
*   User selects country code and enters phone number (pre-filled from agency data if available, but editable)
*   User clicks Continue
*   The system sends a 6-digit OTP via SMS to the entered number
*   The user enters the OTP on the verification screen
*   The system validates OTP and shows successful confirmation
*   The system saves the phone number to the user master as a personal mobile number and marks it as verified
*   User proceeds to the dashboard

### **3.2. First-Login 2FA Setup — Email Flow (Regular User)**

*   2FA setup pop-up appears with Email/SMS options
*   User selects "Set up using Email"
*   User confirms the registered email address (read-only display)
*   User clicks Continue
*   The system sends a 6-digit OTP to the registered email
*   The user enters the OTP on the verification screen
*   The system validates OTP and shows successful confirmation
*   The system marks the email as verified for 2FA purposes
*   User proceeds to the dashboard

### **3.3. First-Login 2FA Setup — Google User**

*   2FA setup pop-up appears with **only** the "Set up using SMS" option (email is pre-verified via Google OAuth, so Email 2FA is not available)
*   User follows the SMS Flow as per 3.1, or clicks Skip (same one-time-only behavior)

**Note:** At first login, the user can enable only **one** method. To activate the second method (or set up 2FA if skipped), the user must go to Settings → 2-Step Verification.

### **3.4. Login Verification When 2FA Is Enabled**

*   User enters credentials (email + password, or Google OAuth) successfully
*   System sends a 6-digit OTP to the user's active 2FA method(s):
    *   **If only one method is active:** OTP is sent to that method
    *   **If both methods are active:** the **same OTP** is sent to **both** Email and SMS simultaneously; an info banner on the OTP screen reads: _"We've sent the code to your email and phone. Enter the code from either to continue."_
*   User enters the OTP on the verification screen (any received code works)
*   On successful OTP validation, the user proceeds to the next step (login-time verification check, then dashboard)
*   OTP verification is required at **every login** when 2FA is enabled

### **3.5. Login-Time Contact Verification (If Not Verified)**

After successful login (and after 2FA OTP verification if applicable), the system checks the verification status of the user's email and phone. If either is not verified, a blocking modal appears before the user reaches the dashboard.

**Email Verification Required:**

*   Modal displays the registered email address + "Verify Email" button
*   User clicks Verify Email
*   System sends a 6-digit OTP to the registered email
*   User enters the OTP; system validates
*   On success, email is marked verified; user proceeds to phone verification (if also required) or to dashboard

**Phone Verification Required:**

*   Modal displays a country code dropdown + phone number input
*   User enters phone number (pre-filled with agency phone if available) and clicks Continue
*   System sends a 6-digit OTP via SMS
*   User enters the OTP; system validates
*   On success, phone is saved to user master and marked verified; user proceeds to dashboard

**Both Unverified:**

*   Email verification is requested first, then phone
*   User must complete both to proceed

**Google Users:**

*   Email is auto-verified via Google OAuth; only phone verification may be required
*   If phone is already on file and verified, no prompt

This flow repeats at every login until the required contacts are verified. There is no "skip" — the prompt is blocking.

## **4\. Functional Logic**

### **4.1 2FA Setup Initiation**

*   First-login 2FA setup pop-up is automatically triggered upon the first successful login if 2FA has never been configured
*   2FA is **optional**; the user may skip once at first login
*   Once skipped, the first-login pop-up is flagged as dismissed and will **not** reappear automatically on subsequent logins
*   To set up 2FA later, the user must navigate to Settings → 2-Step Verification

### **4.2 Method Selection (First-Login vs. Settings)**

*   **First-login pop-up:** user selects **one** method only — Email or SMS (Google users: SMS only)
*   **Settings:** users can activate Email, SMS, or **both** simultaneously (covered in the Global Settings FRD)
*   The first-login flow is intentionally simplified to a single method to minimize friction during onboarding

### **4.3 Phone Number Handling**

*   During first-login SMS setup and login-time phone verification, the phone number is entered in that flow (not required on profile beforehand)
*   Pre-filled with the agency-registered phone number if available, but editable
*   On successful OTP verification, the phone number is saved to the user master as a **personal mobile number**, separate from agency contact information, and marked as verified
*   The same phone number can be used across multiple user accounts (for different agencies or roles)
*   2FA phone numbers do not affect or overwrite agency-registered phone numbers

### **4.4 OTP Generation and Delivery (Login Flows)**

*   OTP is exactly **6 digits, numeric (0–9)**
*   Generated using a cryptographically secure random number generator
*   Valid for exactly **2 minutes** from generation
*   Each OTP is single-use; invalidated after successful use or when a new OTP is generated
*   The system stores hashed OTPs (never plain text)
*   **Single-method active:** OTP delivered via that channel
*   **Both methods active (login 2FA):** the **same OTP** is dispatched to both Email and SMS in a single generation event; entering the code from either channel completes verification
*   **Login-time verification (Section 3.5):** OTP is sent to the channel being verified (email or the newly entered phone number)

### **4.5 OTP Verification**

*   System performs a constant-time comparison against the latest valid OTP for the session
*   Feedback distinguishes between invalid, expired, and already-used codes
*   On successful verification, the user proceeds to the next step (either next verification, or the dashboard)

### **4.6 OTP Attempt Limits**

*   Users have a maximum of **5 OTP entry attempts** per session (unified count regardless of how many channels delivered the code)
*   After 5 wrong attempts: 2FA actions are restricted for **1 hour**
*   Automatic unlock after exactly 1 hour from the lockout time
*   **Login reset:** The 5-attempt counter resets to 0 upon a successful fresh login. If a 1-hour lockout is already active, logging out and logging back in does **not** bypass the lockout — the lockout persists until the full 1 hour has elapsed.

### **4.7 Resend Logic**

*   "Resend Code" is disabled for 60 seconds after each OTP delivery
*   Maximum of **5 resend attempts per session**, counted as a **combined total across SMS and Email** (e.g., 3 SMS resends + 2 Email resends = 5 total; the limit is reached)
*   After 5 resends: user is restricted for **1 hour**
*   Each resend invalidates the previously issued OTP
*   When both methods are active during login 2FA, **Resend re-dispatches the same new code to both Email and SMS**. This counts as **1 resend** against the combined limit, not 2.
*   **Login reset:** The combined resend counter resets to 0 upon a successful fresh login. If a 1-hour lockout is already active, logging out and logging back in does **not** bypass the lockout — the lockout persists for the full 1 hour.

### **4.8 Rate Limiting**

*   SMS sending is rate-limited **per phone number across all accounts** to prevent abuse
*   Enforced server-side based on phone number + sliding time window

### **4.9 Auto-advance and UX**

*   OTP input has 6 individual boxes; entering a digit auto-advances focus to the next box
*   Supports paste (auto-fills all 6 boxes)
*   Empty boxes display "-"
*   Verify button is disabled until all 6 boxes are filled

### **4.10 Login-Time Verification Check**

*   Runs after primary credential validation and after 2FA OTP (if applicable) on every login
*   Checks:
    *   Email verified? (skipped for Google users — always verified via OAuth)
    *   Phone verified? (only checked if the user has a phone on record OR is being prompted to add one)
*   If any required verification is missing, a blocking modal is presented
*   The modal cannot be skipped; the user must verify or log out
*   Verification updates are written to the user master immediately upon success

### **4.11 Data Persistence**

*   2FA status (active/inactive per method), active methods, verified-contact flags, and the "first-login 2FA dismissed" flag are stored in the user master table
*   Audit log records 2FA activation events and contact verification events with timestamp, user ID, method, and source (first-login / settings / login-verification)

### **4.12 Impact**

*   Enabling 2FA adds an OTP step to **every** subsequent login
*   Skipping 2FA at first login means no future auto-prompt; the user must actively visit Settings to enable it
*   Login-time verification blocks login access to the dashboard until all required contacts are verified
*   Activating both 2FA methods does not increase login friction (single OTP, dual delivery)

## **5\. Field Details & Validations**

### **Step 1: 2FA Method Selection (First Login)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Authentication Method

Clickable cards

No (Optional)

Two predefined options: "Set up using Email", "Set up using SMS". Google users see **only** SMS.

Skip

Button

Optional

Bypasses setup; sets "first-login 2FA dismissed" flag (no re-prompt)

Cancel Icon (X)

Button

Optional

Closes pop-up; behaves same as Skip

### **Step 2A: Email Setup (First-Time)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Email Address

Email (Display)

N/A

Read-only display of registered email

Back

Button

Optional

Returns to 2FA method selection

Continue

Button

Yes

Sends OTP to the registered email and proceeds to verification

### **Step 2B: SMS Setup (First-Time)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Country Code

Dropdown

Yes

Valid country code (E.164 format)

Phone Number

Text

Yes

Numeric only, max 15 digits (E.164 total length), format-valid, not on blocked list

Back

Button

Optional

Returns to 2FA method selection

Continue

Button

Yes

Validates format; sends OTP if valid

### **Step 3: OTP Verification (All Login OTP Flows)**

**Field Name**

**Type**

**Required**

**Validation Rules**

Info Text (single channel)

Display Text

Yes

Shows masked email (e.g., j\*\*\*@e\*\*\*\*\*.com) or phone with only last 4 digits visible (e.g., \*\*\*\*1234)

Info Text (dual delivery, login 2FA)

Display Text

Yes

"We've sent the code to your email and phone. Enter the code from either to continue."

OTP Input (6 boxes)

Text

Yes

Single digit per box (0-9), auto-advance, supports paste, shows "-" in empty boxes

Resend Code

Button

Optional

Disabled for 60 seconds after send; max 5 attempts per session (combined across SMS + Email); re-sends to all active channels

Back

Button

Optional

Returns to previous step (setup flow only; not shown in login verification)

Verify

Button

Yes

Disabled until all 6 boxes are filled

### **Login-Time Email Verification Modal**

**Field Name**

**Type**

**Required**

**Validation Rules**

Info Text

Display

Yes

"Please verify your email address to continue."

Email (display)

Display

N/A

Read-only registered email

Verify Email

Button

Yes

Sends OTP to email and proceeds to OTP verification

### **Login-Time Phone Verification Modal**

**Field Name**

**Type**

**Required**

**Validation Rules**

Info Text

Display

Yes

"Please verify your phone number to continue."

Country Code

Dropdown

Yes

Valid country code (E.164 format)

Phone Number

Text

Yes

Numeric only, max 15 digits, format-valid, not on blocked list

Continue

Button

Yes

Sends OTP via SMS and proceeds to OTP verification

### **Step 4: 2FA Setup Confirmation**

**Field Name**

**Type**

**Required**

**Validation Rules**

Success Message

Display Text

Yes

"Successfully Enabled" with a checkmark icon

Method Confirmation

Display Text

Yes

Shows masked destination for the activated method

Info Text

Display Text

Yes

"Authentication codes will be sent to this \[email/number\] at login."

Open Dashboard

Button

Yes

Navigates to the main dashboard

## **6\. Error Message Handling**

**Field**

**Validation Scenario**

**Error Message**

Phone Number

Field empty

"Please enter your phone number."

Phone Number

Invalid format

"Please enter a valid phone number."

Phone Number

Blocked/unsupported number

"This phone number cannot be used for verification."

OTP Input

Invalid OTP

"Incorrect OTP. Please try again."

OTP Input

Expired OTP

"This code has expired. Please request a new one."

OTP Input

Code already used

"This code has already been used. Please request a new one."

OTP Input

5 wrong attempts

"You have entered an incorrect OTP multiple times. Please try again after one hour."

Resend Code

Within cooldown

"Please wait before requesting a new code."

Resend Code

Limit exceeded (5 combined SMS + Email per session)

"Resend limit exceeded. Please try again after one hour."

Email Service

Delivery failure (single channel)

"Unable to send verification code. Please try again."

SMS Service

Delivery failure (single channel)

"Unable to send verification code. Please try again."

Dual Delivery

Partial failure (one channel succeeds)

No error shown; OTP screen proceeds. Info text: "We've sent the code to your \[email/phone\]. The other channel is temporarily unavailable."

Dual Delivery

Both channels fail

"Unable to send verification code. Please try again."

General

Service unavailable

"Something went wrong. Please try again."

General

Network timeout

"Something went wrong. Please try again."

## **7\. Edge Cases**

**Scenario**

**Expected Behavior**

User closes browser during incomplete 2FA setup

Session state discarded; next login does NOT re-trigger the first-login pop-up (treated as skipped)

User closes browser during login-time verification

Session expires; verification required again on next login

Email/SMS service unavailable during OTP send (single channel)

Display error; allow retry without consuming a resend attempt

Network connectivity issues during OTP sending

Show error message; allow retry without consuming a resend attempt

International phone number with complex formatting

System normalizes to E.164 before validation and storage

User logs out during OTP verification

Session expires; user must restart from login

Multiple rapid resend attempts

Enforce 60-second cooldown; taps within the window are ignored

System clock discrepancy affecting OTP timing

Use server-side timestamps exclusively for generation and validation

Agency admin changes 2FA phone number (from Settings)

New number saved to user master; agency phone unchanged

Same phone used for 2FA across multiple accounts

Allowed; per-phone rate limit still applies

Google user attempts Email 2FA during first-login

Not possible; only SMS option is shown

User skipped 2FA and later wants it

Must navigate to Settings → 2-Step Verification (no auto-reprompt)

Both methods active, one channel delivery fails at login

Login proceeds using the successful channel; info text adjusts

Both methods active, both channels fail at login

Generic delivery error; user can retry; resend counter not incremented

User enters the email OTP while the SMS OTP also arrives

First valid entry succeeds; SMS code (same value) is also valid if entered

User has phone on file that is unverified when login-time check runs

Shown phone verification prompt with number pre-filled; can edit if incorrect

Login-time verification completed but session expires before reaching dashboard

Verification persists in user master; next login skips that step

User hits resend or attempt limit, then logs out and back in

Counters (both resend and OTP entry) reset to 0 on the next fresh login; however, any active 1-hour lockout remains enforced regardless of re-login

User exhausts resends across a mix of SMS and Email during login 2FA

Combined SMS + Email resends count toward the same 5-attempt session limit; hitting 5 triggers the 1-hour lockout

## **8\. Acceptance Criteria**

*   **Setup Initiation:** First-login 2FA setup pop-up appears exactly once for new users and is skippable
*   **No Reminder:** If the user skips, the pop-up does not reappear at subsequent logins
*   **First-Login Single Method:** First-login flow allows only one method; second method added later via Settings
*   **Login Multi-Method Delivery:** When both 2FA methods are active, the same OTP is delivered to both channels at login
*   **Every-Login OTP:** When 2FA is enabled, OTP verification is required at every login (no device-trust bypass)
*   **Login-Time Verification:** If the user's email or phone is not verified, a blocking verification flow runs at every login until completed
*   **Google User Support:** Google users see only the SMS option at first-login; Email 2FA is not available to them; email is treated as verified via OAuth at login-time verification
*   **Field Validation:** All input fields are validated according to specified rules before progression
*   **OTP Rules:** OTP is 6 digits, expires in 2 minutes, single-use; 5 wrong attempts trigger a 1-hour lockout; 5 resends (combined across SMS and Email) trigger a 1-hour lockout; 60-second cooldown between resends
*   **Counter Reset on Login:** OTP entry-attempt and resend counters reset to 0 on every successful fresh login; active 1-hour lockouts are not bypassed by re-login
*   **Phone Number Storage:** Phone number is saved to the user master as personal mobile, independent of agency contact info
*   **Rate Limiting:** SMS rate limiting applies per phone number across all accounts
*   **Agency Data Separation:** User 2FA phone numbers do not overwrite agency contact information
*   **Auto-advance:** OTP fields automatically focus the next field upon character entry
*   **Automatic Unlock:** Locked accounts unlock automatically after exactly 1 hour
*   **Error Handling:** All error scenarios display the appropriate message per Section 6
*   **Success Confirmation:** Successful setup shows confirmation with selected method details
*   **Audit Logging:** 2FA activation and verification events are recorded with timestamp, user ID, method, and source

## **9\. Dependencies**

**Module/System**

**Dependency Type**

**Impact if Unavailable**

Email Service Provider

External Integration

Email OTP delivery fails; email-based 2FA and email verification cannot be completed; dual delivery falls back to SMS only

SMS Service Provider

External Integration

SMS OTP delivery fails; SMS-based 2FA and phone verification cannot be completed; dual delivery falls back to Email only

OTP Generation Service

Internal Dependency

Cannot generate codes; 2FA setup, login verification, and contact verification halted

User Authentication System

Internal Dependency

Cannot validate user credentials or session state

User Master Database

Data Dependency

Cannot store personal phone number, 2FA preferences, or verification flags

Agency Master Database

Data Dependency

Cannot pre-populate agency phone numbers for default suggestions

Google OAuth Service

External Integration

Google users cannot sign in

Session Management

Internal Dependency

Cannot maintain user state during the multi-step flows

Phone Number Validation Service

External Integration

Cannot validate phone numbers or detect blocked numbers

Rate Limiting Service

Internal Dependency

Cannot prevent SMS abuse across platform accounts

Audit Log Service

Internal Dependency

2FA and verification events not recorded; compliance impacted

## **10\. References**

*   **Figma Prototype Link:** [Click here](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13406-300945&t=ksWBAHb4a3i1V5rH-0)
*   **Related FRD:** Global Settings – 2-Step Verification (management flows)
*   **Related FRD:** Contractor Portal – 2FA (contractor-portal 2FA setup, login verification, and pre-onboarding 2FA placement)