Authentication & Authorization - Product Requirements Document

Version: 2.0 | Status: Business Review | Date: 2026-01-15 Previous Version: 1.0 (Technical Draft) | Author: Product Team

Change Log

Version	Date	Changes
2.0	2026-01-15	Converted to business-focused format; added measurable outcomes and success metrics
1.0	2026-01-09	Initial technical draft

1. Executive Summary

1.1 Purpose

Enable secure, passwordless access to Toprent.app through magic link authentication, enforcing role-based permissions across all user types. Users authenticate once and access multiple rental companies with appropriate permissions per company.

1.2 Business Value

Value Area	Measurable Outcome	Timeframe
Support Cost Reduction	Reduce password-related support tickets by 80% (industry: 20-50% of help desk volume is password resets)	Within 6 months
User Activation	Increase first-login completion rate from ~70% to 90%+ with frictionless magic links	Within 3 months
Security Incidents	Zero unauthorized access incidents through passwordless + optional MFA	Ongoing
Multi-Business Efficiency	Enable users managing multiple companies to switch contexts in <3 seconds vs. logging out/in	Immediate
Compliance Readiness	MFA capability meets financial data security requirements without mandating enrollment	Immediate

1.3 Target Users

User Type	Business Context
Company Administrators	Full system access, user management, billing, financial data
Company Operators	Day-to-day operations: reservations, customer management, vehicles
Vehicle Partners	Limited access to their vehicles, calendar, and offer calculator
Drivers (Couriers/Staff)	View-only access to assigned reservations and delivery tasks

1.4 Scope

Included:

Passwordless magic link authentication
Optional SMS-based multi-factor authentication
Four-role permission system (Admin, Operator, Partner, Driver)
Multi-company user access with per-company roles
Seamless company switching without re-login
Permission-based UI visibility controls
Session management with automatic refresh

Excluded:

Password-based authentication (legacy, being phased out)
TOTP/authenticator app MFA (future consideration)
Third-party SSO (OAuth, SAML)
Biometric authentication
Self-service user registration (separate feature)

Note: Password reset and change password remain active for legacy users during transition.

2. Success Metrics

Metric	Definition	Baseline	Target	Measurement Method
Password Ticket Reduction	Monthly support tickets for password issues	To be measured	80% reduction within 6 months	Help desk ticket categorization
Magic Link Delivery Rate	% of magic links delivered within 5 seconds	N/A (new)	>99%	Email delivery logs
First-Login Completion	% of invited users completing sign-in within 24 hours	~70% (est.)	>90%	User analytics
MFA Adoption Rate	% of Admin users enabling MFA	N/A (new)	50% within 12 months	User settings analytics
Session Continuity	% of active sessions maintained without interruption	N/A (new)	>99.5%	Session refresh logs
Company Switch Time	Average time to switch between companies	N/A (new)	<3 seconds	Performance monitoring
Unauthorized Access Incidents	Security incidents from authentication failures	0	0 (maintain)	Security audit logs
Authentication Success Rate	% of sign-in attempts completing successfully	N/A (new)	>98%	Authentication analytics
Role Permission Violations	API requests blocked due to insufficient permissions	N/A (new)	Track & monitor	API access logs

3. User Stories

Administrators (P0 - Critical)

ID	Story	Acceptance Criteria
US-01	As an Admin, I want to sign in via magic link so I don’t need to remember passwords	Given I enter my email, when I submit, then I receive a sign-in link within 5 seconds; clicking it authenticates me
US-02	As an Admin, I want to select which company to access after signing in so I can manage multiple businesses	Given I have access to multiple companies, when I authenticate, then I see all my companies with my role for each
US-03	As an Admin, I want to switch companies without logging out so I work efficiently across businesses	Given I’m authenticated, when I select another company from the menu, then I switch contexts in <3 seconds
US-04	As an Admin, I want my session to remain active while working so I don’t re-authenticate repeatedly	Given I’m active, when my session approaches expiration, then it refreshes automatically without interruption

Administrators (P1 - Important)

ID	Story	Acceptance Criteria
US-05	As an Admin, I want to enable MFA so financial data has additional protection	Given I enable MFA, when I sign in, then I must enter SMS code before accessing the system
US-06	As an Admin, I want to create users with specific roles so I control feature access	Given I create a user, when I assign a role, then they see only permitted features
US-07	As an Admin, I want to customize permissions per user so I can fine-tune access beyond default roles	Given I edit user permissions, when I disable calendar access, then that user cannot see calendar features
US-08	As an Admin, I want to view authentication audit logs so I can monitor account security	Given suspicious activity, when I view logs, then I see all sign-in events with timestamps and outcomes

Operators (P0 - Critical)

ID	Story	Acceptance Criteria
US-09	As an Operator, I want to sign in quickly via magic link so I can process reservations	Given I click my magic link, when I authenticate, then I land on my working dashboard in <10 seconds total
US-10	As an Operator, I want to see only features I’m permitted to use so the interface isn’t cluttered	Given my role permissions, when I view navigation, then inaccessible features are hidden

Operators (P1 - Important)

ID	Story	Acceptance Criteria
US-11	As an Operator, I want to switch between companies I work for without logging out	Given I work for multiple companies, when I switch, then I see that company’s data immediately
US-12	As an Operator, I want the system to remember my last company so I save time on subsequent logins	Given I have a preferred company, when I sign in, then my last-used company is pre-selected

Partners (P0 - Critical)

ID	Story	Acceptance Criteria
US-13	As a Partner, I want to sign in and see my vehicle calendar immediately	Given I authenticate, when I land, then my calendar view loads showing only my vehicles

Partners (P1 - Important)

ID	Story	Acceptance Criteria
US-14	As a Partner, I want access to the calculator to view offers for my vehicles	Given I have calculator permission, when I access it, then I see offers relevant to my fleet
US-15	As a Partner, I want restricted access so I only see my own vehicles	Given I view vehicles, when results load, then only vehicles I own are visible

Drivers (P0 - Critical)

ID	Story	Acceptance Criteria
US-16	As a Driver, I want to sign in and see only my assigned reservations	Given I authenticate, when I land, then only my delivery tasks are visible
US-17	As a Driver, I want view-only access so I can’t accidentally modify bookings	Given I view a reservation, when I attempt edits, then modification controls are hidden/disabled

All Users (P0 - Critical)

ID	Story	Acceptance Criteria
US-18	As any user, I want magic links to expire for security if compromised	Given a magic link, when 60 minutes pass, then it no longer works
US-19	As any user, I want my session to auto-refresh so I stay signed in during work	Given I’m active, when tokens approach expiration, then refresh happens invisibly
US-20	As any multi-company user, I want to see all my companies after authentication	Given I have multiple company access, when I sign in, then all companies display with my role for each

All Users (P1 - Important)

ID	Story	Acceptance Criteria
US-21	As any user, I want clear error messages if authentication fails	Given a failure, when I see the error, then I understand how to resolve it
US-22	As any user, I want to cancel MFA verification to try a different account	Given I’m in MFA flow, when I cancel, then I return to sign-in with state cleared

4. Functional Requirements

ID	Requirement	Priority	Business Rationale
FR-01	Magic links must be delivered within 5 seconds and expire after 60 minutes	P0	Balances user convenience with security
FR-02	System must protect against email enumeration (always return success message)	P0	Security best practice; prevents account discovery attacks
FR-03	Users can belong to multiple companies with different roles per company	P0	Supports consultants, franchise operators, multi-location businesses
FR-04	Company selection appears after authentication showing all accessible companies with roles	P0	Multi-tenant user experience requirement
FR-05	Company switching must complete without re-authentication	P0	Efficiency for multi-business users
FR-06	System enforces four roles: Administrator, Operator, Partner, Driver	P0	Clear permission boundaries
FR-07	Role permissions enforced at both UI (hidden components) and API (blocked requests) levels	P0	Defense in depth; prevents bypass via direct API calls
FR-08	SMS verification codes (6 digits) must deliver within 10 seconds and expire after 5 minutes	P1	MFA user experience balance
FR-09	MFA attempts must be rate-limited to prevent brute force attacks	P1	Security requirement
FR-10	SMS resend allowed after 30-second cooldown with maximum 5 resends per session	P1	Anti-abuse while allowing recovery
FR-11	Session tokens valid for 30 days with automatic refresh before expiration	P0	Continuous work sessions without interruption
FR-12	Sessions scoped to specific company context	P0	Multi-tenant data isolation
FR-13	Admins can customize user permissions beyond default roles	P1	Fine-grained access control (calendar, offers, billing, contacts visibility)
FR-14	All authentication events logged to audit trail	P1	Security compliance and monitoring
FR-15	Users routed to role-appropriate landing pages after authentication	P1	Driver→reservations, Partner→calendar, Admin/Operator→dashboard
FR-16	System auto-selects company if user has only one	P0	Streamlined experience for single-company users
FR-17	ADMIN role company preferred for auto-selection when multiple exist	P1	Prioritizes highest-privilege context
FR-18	Non-ADMIN users can leave companies they belong to	P1	Self-service access management
FR-19	Sign-out clears all authentication state and redirects to sign-in	P0	Security requirement

5. Business Rules

ID	Rule	Business Rationale
BR-01	Magic links can only be used once	Prevents replay attacks
BR-02	One role per user per company	Simplifies permission logic; clear accountability
BR-03	ADMIN role has unrestricted access within their company	Business requirement for full control
BR-04	Partners can only view vehicles they own	Privacy and competitive protection
BR-05	Drivers have read-only access to reservations	Prevents accidental modifications
BR-06	MFA enrollment is optional, not enforced	Balances security with user choice
BR-07	MFA phone must be verified before enabling	Prevents lockout from typos
BR-08	Custom permissions override default role permissions	Enables exceptions without creating new roles
BR-09	Users removed from a company persist if they have other company access	Data preservation for multi-company users
BR-10	ADMINs cannot leave their own company	Prevents ownership orphaning
BR-11	Authentication errors return generic messages	Prevents information leakage
BR-12	Public pages (sign-in, confirmation) bypass authentication	User experience requirement

6. Acceptance Criteria

AC-01: Magic Link Authentication Flow

Given a user with an existing account
When they enter their email and submit
Then they receive a magic link within 5 seconds
And clicking the link authenticates them
And the link expires after 60 minutes
And the link works only once

AC-02: Email Enumeration Protection

Given a user enters an email that doesn’t exist
When they submit the sign-in form
Then the system returns a success message
And no email is sent
And behavior is indistinguishable from valid email submission

AC-03: Multi-Company Selection

Given a user with access to multiple companies
When they complete authentication
Then they see all associated companies with their role for each
And they can select which company to access
And single-company users skip selection automatically

AC-04: Company Switching

Given a user authenticated to a specific company
When they select another company from the profile menu
Then they switch to that company in <3 seconds
And no re-authentication is required
And they land on the role-appropriate page for the new company

AC-05: MFA Verification

Given a user with MFA enabled
When they complete initial authentication
Then they receive a 6-digit SMS code within 10 seconds
And entering correct code within 5 minutes completes authentication
And incorrect codes show clear error with retry option
And cancel returns them to sign-in with state cleared

AC-06: Role-Based Access (Driver)

Given an authenticated user with Driver role
When they access the application
Then they see only the reservations page
And other navigation items are hidden
And API requests to restricted resources return forbidden errors

AC-07: Role-Based Access (Partner)

Given an authenticated user with Partner role
When they access the application
Then they see calendar and calculator pages
And they only view vehicles they own
And they cannot create or modify reservations

AC-08: Role-Based Access (Operator)

Given an authenticated user with Operator role
When they access the application
Then they can create reservations, manage customers, and view vehicles
And they cannot access billing, admin statistics, or user management

AC-09: Role-Based Access (Administrator)

Given an authenticated user with Administrator role
When they access the application
Then they have unrestricted access to all features
And they can create users with any role
And they can modify system settings

AC-10: Session Continuity

Given an authenticated user
When their session approaches expiration during active work
Then the token refreshes automatically
And the user experiences no interruption

AC-11: Sign-Out Security

Given an authenticated user
When they sign out
Then all session data is cleared
And they are redirected to sign-in
And subsequent API requests return unauthorized errors

7. Dependencies

7.1 Depends On

01-Multi-Tenant Architecture: User-company associations and per-company role assignments

7.2 Depended By

All user-facing features require authentication:

Reservations Management
Vehicle Fleet Management
Customer Management
Billing & Invoicing
Marketplace Features
Reports & Analytics

7.3 External Services

Email delivery system (magic link sending)
SMS provider (MFA codes)
reCAPTCHA (bot protection for MFA)

8. Glossary

Term	Business Definition
Magic Link	Single-use URL sent via email that authenticates user without password
MFA (Multi-Factor Authentication)	Additional SMS verification step for enhanced account security
Role	User’s permission level within a company (Administrator, Operator, Partner, Driver)
Permission Gate	Feature visibility control based on user’s role permissions
Session	Period of authenticated access, maintained across browser sessions
Company Switching	Changing active company context without re-authenticating
Custom Permission	User-specific access override (e.g., calendar access, billing visibility)
Driver/Courier/Staff	Interchangeable terms for delivery personnel role

9. Approval

Role	Name	Date	Status
Product Owner			Pending
Engineering Lead			Pending
Security Review			Pending
Business Stakeholder			Pending

10. Unresolved Questions

Password phase-out timeline? When to fully deprecate password login?
MFA enforcement policy? Should MFA be mandatory for ADMIN role accessing financial data?
Session duration by role? Should Drivers have shorter sessions than Admins for security?
TOTP MFA priority? When to add authenticator app option vs. SMS-only?
SSO roadmap? Enterprise customer demand for OAuth/SAML integration?