OTP management.

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:

1. User enters their email address
2. System generates a secure 6-digit code
3. The system sends the code by email
4. User enters the code to verify identity
5. 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.

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

• Required for all profile changes
• Verifies user identity before saving
• Replaces "enter current password" verification
• 30-minute grace period: verify once and save multiple times without re-entering a code

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

The activity log system records all OTP events:

• OTP code generation
• Successful verifications
• Failed verification attempts
• Rate limit violations

To view OTP activity:

1. Navigate to Activity logs
2. Filter by category: "authentication"
3. 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)

Rate limit hits: Frequent rate limiting may indicate:

• Spam/abuse attempts
• Email delivery issues causing repeated requests

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:

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