Skip to main content

Source: ocean/docs/PASSWORDLESS_AUTH.md | ✏️ Edit on GitHub

Passwordless Authentication System

This application uses passwordless authentication with OTP (One-Time Password) codes sent via email. No passwords are stored or required.

How it Works​

For New Users (Sign Up)​

  1. User enters email and profile information
  2. System sends a 6-digit OTP code to their email
  3. User enters the code to verify and create account
  4. User is automatically logged in

For Existing Users (Login)​

  1. User enters only their email address
  2. System sends a 6-digit OTP code to their email
  3. User enters the code to authenticate
  4. User is logged in

Benefits​

✅ No Password Vulnerabilities

  • No weak passwords
  • No password reuse
  • No password breaches
  • No forgotten passwords

✅ Enhanced Security

  • Each login requires email access
  • OTP codes expire in 5 minutes
  • No credentials to steal or phish

✅ Better User Experience

  • No password requirements to remember
  • Simple email-only login
  • Fast authentication flow

Authentication Flow​

User → Enter Email → Receive OTP → Enter Code → Authenticated

API Methods​

authService.signUpPasswordless(data)​

Creates a new user account without password

  • email: User's email address
  • metadata: Additional user data (industry, region, etc.)

authService.signInPasswordless(email)​

Sends OTP to existing user's email

  • email: User's email address

authService.verifyOtp(email, token, type)​

Verifies the OTP code

  • email: User's email address
  • token: 6-digit OTP code
  • type: Either 'signup' or 'magiclink'

Email Templates​

The system sends OTP codes in emails with:

  • Clear 6-digit code display
  • 5-minute expiration notice
  • No clickable links (security feature)

Testing​

⚠️ CRITICAL: Only Use Real Emails​

Your project has high bounce rates and is at risk of losing email privileges!

Safe Test Emails​

  • ryan@goldfish.io (your primary)
  • ryan+test1@goldfish.io, ryan+test2@goldfish.io (for multiple tests)
  • All +suffix emails deliver to your main inbox

Testing Flow​

  1. New User: Go to homepage, enter real email, receive code, verify
  2. Existing User: Go to /login, enter real email, receive code, verify
  3. DO NOT use fake emails like test@example.com or random@gmail.com

Security Considerations​

  • OTP codes are single-use
  • Codes expire after 5 minutes
  • Email verification required for all accounts
  • No passwords stored in database
  • Rate limiting on OTP requests (1 per minute)