OTP management.
Configure and maintain the one-time password authentication system
The OTP (One-Time Password) authentication system provides passwordless login across all user types. This guide covers how the system works, security features, and maintenance tasks for administrators.
How OTP authentication works
When users sign in with a verification code:
- User enters their email address
- System generates a secure 6-digit code
- The system sends the code by email
- User enters the code to verify identity
- System validates and creates authenticated session
Codes are single-use, time-limited, and cryptographically secure.
Security features
Code generation
Cryptographically secure: The system generates codes with secure random number generation, not predictable patterns.
Weak pattern exclusion: The system never generates codes that are easy to guess, like:
- Sequential: 123456, 654321
- Repeated: 111111, 222222, 333333
- Common: 000000, 999999
Hashed storage: The system hashes codes before storing them. It never saves plain-text codes in the database.
Rate limiting
Request limits: Maximum 5 OTP requests per email per 5 minutes.
Resend cooldown: 60-second wait between resend requests.
Public authentication pages also apply these request limits separately for members, partners, staff, and administrators:
| Request | Per account | Per IP address |
|---|---|---|
| Password login and code verification | 10 per minute | 120 per minute |
| Email checks | 20 per minute | 120 per minute |
| Code delivery, recovery, and registration submissions | 5 per 5 minutes | 60 per minute |
Invalid registration submissions count toward the request limit, even if no email goes out. Partner registration also allows five submissions per ten minutes per IP address. When a request reaches a limit, the page shows the wait time; wait before trying again.
Purpose: Prevents abuse and spam attacks.
Attempt limits
Maximum attempts: 5 verification attempts per code.
Auto-lock: After 5 failed attempts, the code locks and no longer works.
User action: User must request a new code to try again.
Time limits
Code expiration: 10 minutes from generation.
Session tokens: Profile verification tokens expire after 30 minutes. Within that window, additional saves skip re-verification.
Purpose: Limits the window for potential attacks.
OTP use cases
The system uses OTP codes for:
Login authentication
- All user types (Customers, Staff, Partners, Administrators)
- Alternative to password login
- Primary method for passwordless accounts
- Members created from connected store orders (Shopify or WooCommerce) have no password and sign in with a one-time code
Registration verification
- Customer registration email verification
- Partner registration email verification (when enabled)
- Ensures valid email addresses
Profile updates
Account settings uses Personal details, Security and Language and time zone where applicable. Short forms keep these as sections. Member accounts retain their privacy, account-switching and physical-card panels.
- Required for administrator, partner, staff and member profile changes
- Verifies user identity before saving
- Replaces current-password verification on these accounts
- 30-minute grace period: verify once and save multiple times without re-entering a code
After editing Account settings, select Continue to verification. The dialog asks you to Send verification code, enter the six-digit code, and select Verify and save. Cancelling the dialog keeps your edits. While verification remains valid, the form offers Save changes.
Member profile changes verify the submitted email address. Partner, staff, and administrator profile changes verify the current saved account email. Business settings does not require this profile verification.
Dashboard create and edit forms ask before leaving unsaved changes. Choose Stay to keep editing or Discard changes to leave. Cancelling verification keeps the form unsaved; a failed save keeps your entered values for correction. The form does not save a draft.
When validation fails, the form opens the section containing the first available invalid field and moves focus there. Tab counts help you find errors in other sections. Correct the fields and submit again.
Account login (anonymous members)
- Sign in to an existing account from the Switch Account tab
- Verifies email ownership before switching sessions
- Available when anonymous mode is enabled
Database storage
The system stores OTP codes in the otp_codes table with:
Security tracking:
- Hashed code (not plain text)
- IP address of request
- User agent (browser/device)
- Attempt counter
Metadata:
- Purpose (login, verify_email, profile_update)
- Guard (member, staff, partner, admin)
- Expiration timestamp
- Verification status
Retention: A scheduled command cleans up verified and expired codes.
Maintenance commands
Automatic cleanup
The system includes a scheduled command to remove old OTP codes:
php artisan otp:cleanup
What it does:
- Removes all codes older than 24 hours, verified and expired alike
- Keeps the last 24 hours of codes for security logging
Schedule: The hourly run ships with the app in routes/console.php; there is nothing to add:
// routes/console.php (included with the app)
Schedule::command('otp:cleanup --hours=24')->hourly();
The command runs on its own once your server's cron entry calls the Laravel scheduler every minute (see the Health center). Without cron, codes still expire and become unusable on schedule; only the database cleanup waits until you run the command by hand.
Manual cleanup
To clean up OTP codes by hand:
php artisan otp:cleanup
Run this if:
- The scheduled task isn't running
- You need to free database space now
- You're troubleshooting OTP issues
Monitoring OTP activity
Activity logs
Activity logs include sent codes, successful verification or sign-in, and failed verification attempts.
To view OTP activity:
- Navigate to Activity logs
- Filter by category: "authentication"
- Look for OTP-related events
Security monitoring
Watch for:
High failure rates: Many failed OTP verifications may indicate:
- User confusion (provide better instructions)
- Attack attempts (investigate IP addresses)
Repeated code requests: Many sent-code events for the same account may indicate abuse or delivery problems that cause the user to request another code.
Unusual patterns: Multiple OTP requests from same IP for different emails may indicate:
- Automated attacks
- Need for additional security measures
Configuration
The application code sets OTP settings:
| Setting | Value | Notes |
|---|---|---|
| Code length | 6 digits | Standard |
| Expiration time | 10 minutes | Security requirement |
| Maximum attempts | 5 per code | Prevents brute force |
| Rate limit | 5 requests per 5 minutes | Prevents spam |
| Resend cooldown | 60 seconds | Prevents abuse |
Don't change these security-critical values without careful consideration.
Email delivery
The configured email system sends OTP codes. Ensure:
SMTP is configured: Check email settings in administration.
Email queue is running: If using queues, ensure workers are active.
Delivery is reliable: Test email delivery often.
Spam filters: Verify spam filters aren't catching OTP emails.
Troubleshooting
Users not receiving codes
Check email configuration: Verify SMTP settings are correct.
Check queue workers: If using queues, ensure they're running.
Check spam folders: Advise users to check spam/junk.
High failure rates
Review activity logs: Check for patterns in failed attempts.
Check code expiration: Ensure the 10-minute window is enough.
Verify email delivery speed: Slow delivery may cause expiration.
Database growth
Run cleanup command: Execute php artisan otp:cleanup
Verify scheduler is running: Check that Laravel scheduler runs every minute.
Best practices
Run cleanup hourly: Keep the OTP table size manageable.
Monitor activity logs: Watch for suspicious patterns.
Test email delivery: Verify OTP emails arrive on time.
Educate users: Provide clear instructions on using OTP codes.
Secure email system: Protect your SMTP credentials.
Related topics
- Authentication overview: All authentication options
- Activity logs: Monitor OTP usage
- Security monitoring: Detect suspicious activity