Authentication Features¶
Feature capabilities and business value for project owners and stakeholders.
Core Features¶
User Registration¶
Two Registration Paths:
| Path | Description | Use Case |
|---|---|---|
| Door A | Create user + team | New customers starting from scratch |
| Door B | Join existing team | Invited team members |
Business Value: - Reduces friction for team onboarding - Allows trial-to-paid conversion flow - Enables viral growth via team invitations
Capabilities: - Email verification required (prevents fake accounts) - Team creation with custom slug - Automatic Owner role assignment - Billing integration (Virtuozzo groupType check)
Multi-Team Support¶
Description: Users can belong to multiple teams with different roles.
Use Cases: - Agency managing multiple client sites - Consultants working with multiple organizations - Users with personal + work accounts
Capabilities:
- Team switching via /auth/session-exchange
- Role scoping per team
- Independent sessions per team
Role-Based Access Control (RBAC)¶
Description: Flexible permission system with custom roles.
Default Roles:
| Role | Permissions | Use Case |
|---|---|---|
| Owner | * (all) |
Full control, billing |
| Manager | Team + resources (no billing) | Team management |
| Developer | Resources only | Development work |
Custom Roles: - Create unlimited custom roles - Assign any combination of permissions - Editable (except Owner role)
Business Value: - Granular access control - Separation of duties - Scalable permission model
Security Features¶
Device Approval¶
Description: New devices require email OTP approval.
Flow: 1. User logs in from new device 2. Email sent with 6-digit OTP 3. User enters OTP to approve device 4. Device remembered for future logins
Business Value: - Prevents unauthorized device access - Alerts users to suspicious activity - Reduces account takeover risk
Configuration: - 5-minute OTP TTL - Max 5 verification attempts - Per-user and per-IP rate limiting
Suspicious Login Detection¶
Description: Geo-IP based anomaly detection.
Triggers: - New IP address - New geographic location - New device fingerprint
Actions: - Email user with approve/deny links - Block login until decision - Audit all suspicious activity
Business Value: - Proactive fraud detection - User control over account access - Compliance with security best practices
Concurrent Login Control¶
Description: Single active session per user.
Options: - Approve new login (revokes old session) - Deny new login (keeps current session)
Business Value: - Prevents account sharing - Improves security posture - User control over concurrent access
Session Management¶
Configurable Timeouts¶
| Timeout | Default | Description |
|---|---|---|
| Idle | 60 minutes | Auto-logout after inactivity |
| Absolute | 7 days / 1 day | Forced re-authentication period |
| Remember Me | User choice | 7 days if checked, 1 day if not |
Business Value: - Balance security vs. convenience - Configurable per security policy - User-controlled persistence
Session Visibility¶
Capabilities:
- View all active sessions via /api/v1/auth/login-activity
- See device, IP, location for each login
- Revoke specific sessions via /api/v1/auth/trusted-devices/revoke
Business Value: - User security awareness - Self-service session management - Audit trail for compliance
Account Recovery¶
Password Reset¶
Flow: 1. User requests reset via email 2. Single-use token emailed (1-hour TTL) 3. User sets new password 4. All sessions revoked
Business Value: - Reduces support burden - Self-service recovery - Secure token-based flow
Email Verification¶
Flow: 1. User registers → verification email sent 2. User clicks link → account verified 3. Login blocked until verified
Business Value: - Prevents fake accounts - Verifies email ownership - Reduces spam
Team Management¶
Team Invitations¶
Flow: 1. Owner/Manager creates invitation 2. Single-use token emailed (7-day TTL) 3. User registers via invite link 4. Automatically joins team with assigned role
Business Value: - Streamlined onboarding - Viral growth mechanism - Role-based invitations
Ownership Transfer¶
Flow: 1. Current Owner initiates transfer 2. Email sent to new Owner 3. New Owner accepts transfer 4. Roles updated automatically
Business Value: - Business continuity - Smooth succession planning - Audit trail for transfers
Integration Features¶
Virtuozzo Integration¶
Capabilities: - Team-scoped session keys - Owner-only refresh - Lazy refresh with safety window - Automatic caching
Business Value: - Seamless infrastructure access - Security through Owner-only control - Performance through caching
API Access¶
Capabilities: - RESTful API with 21+ endpoints - JWT-based authentication - Permission-based authorization - OpenAPI documentation (Swagger/ReDoc)
Business Value: - Easy integration with frontend - Third-party integration ready - Self-service documentation
User Experience¶
Two-Step Login¶
Benefits: - Team selection for multi-team users - Pre-auth token timeout (5 min) - Reduced password re-entry
Device Trust¶
Benefits: - Remember approved devices - Skip OTP on trusted devices - Revoke devices anytime
Session Persistence¶
Benefits: - "Remember me" option - 7-day vs 1-day session TTL - User-controlled preference
Analytics & Reporting¶
Available Metrics¶
| Metric | Description |
|---|---|
| Login Success Rate | % of successful logins |
| Failed Login Rate | % of failed logins |
| Suspicious Login Rate | % flagged as suspicious |
| Device Approval Rate | % requiring OTP |
| Session Duration | Average session length |
| Password Reset Rate | % using reset flow |
Audit Reports¶
| Report | Description |
|---|---|
| Login History | All user logins with IP/geo |
| Permission Changes | Role/permission modifications |
| Team Changes | Invitations, ownership transfers |
| Security Events | Suspicious activity, denials |
Roadmap Features¶
Planned (Q2 2025)¶
| Feature | Description | Priority |
|---|---|---|
| SSO Integration | SAML/OAuth providers | High |
| Bulk User Import | CSV import | Medium |
| Advanced 2FA | WebAuthn, hardware keys | Medium |
| Session Analytics | Visualize login patterns | Medium |
Future (2025+)¶
| Feature | Description | Priority |
|---|---|---|
| Adaptive MFA | Risk-based step-up auth | High |
| Biometric Auth | WebAuthn passkeys | Medium |
| Passwordless | Magic link authentication | Low |
Related Documentation¶
- User Experience - UX considerations
- Cost Considerations - Cost implications
- Tasks & Roadmap - Implementation timeline