Understanding Passwordless Authentication

HomeStar uses passwordless magic link authentication instead of traditional passwords for favorites sync and account access.

What Are Magic Links?

A magic link is a single-use URL sent to your email that logs you in when clicked. No password to remember, no typing required.

Here’s how it works:

1. You enter your email address
2. We send you a unique link via email
3. You click the link
4. You’re instantly authenticated

That’s it. No password creation, no “forgot password” flow, no security questions.

Why Magic Links?

No Passwords to Forget

Nothing to remember, nothing to write down, nothing to lose.

More Secure

Magic links expire in 15 minutes and work only once—can’t be reused or stolen.

Faster Access

Click the link and you’re in—no typing passwords on mobile keyboards.

Cross-Device Ready

Check email on your phone, click the link, instantly synced.

Security Benefits

Passwords Are Vulnerable

Traditional passwords have significant security issues:

• Weak passwords — Users choose “password123” or reuse passwords
• Phishing targets — Fake login pages steal passwords
• Database breaches — Leaked password hashes can be cracked
• Password reset flows — Often the weakest link in security

Magic Links Are Stronger

Magic links eliminate these vulnerabilities:

Feature	Security Benefit
Time-limited	Links expire in 15 minutes, minimizing exposure window
Single-use	Once clicked, the link is invalidated—can’t be reused
Email verification	Proves you control the email address
No stored secrets	No password hashes to leak in a database breach
Unique tokens	Each link is cryptographically unique

Note

Magic links use JWT (JSON Web Tokens) with cryptographic signatures that are virtually impossible to forge.

User Experience Benefits

Eliminates Password Friction

Traditional authentication flow:

1. Choose a password (minimum 8 characters, uppercase, lowercase, number, symbol)
2. Retype password to confirm
3. Inevitably forget password
4. Click “Forgot password”
5. Wait for reset email
6. Create new password
7. Forget new password
8. Repeat

Magic link flow:

1. Enter email
2. Click link
3. Done

Perfect for Mobile

Typing complex passwords on mobile keyboards is painful. Magic links eliminate this entirely—just tap the link in your email app.

Cross-Device Seamless

Traditional flow: “Did I use my work email or personal email? Which password did I use?”

Magic link flow: “I’ll just use this email and click the link.”

How We Implement It

Generation

When you request a magic link:

1. Server generates a cryptographically secure random token
2. Token is stored with your email and expiration timestamp
3. Link is constructed: https://yoursite.com/auth/verify?token=abc123...
4. Email is sent with the link

Verification

When you click the link:

1. Server extracts the token from the URL
2. Checks if token exists and hasn’t expired (15 minutes)
3. Verifies token hasn’t been used before
4. Issues a JWT session token for your browser
5. Invalidates the magic link token
6. Redirects you to the favorites page

Session Management

After authentication:

• JWT stored in localStorage — Authenticates future API requests
• Session expires after 30 days — Security balance with convenience
• Sign out available — Clears JWT and disconnects sync

Privacy Considerations

Email Usage

We use your email only for authentication and favorites sync. Specifically:

• ✅ Sending magic links
• ✅ Syncing favorites across devices
• ✅ Identifying your session
• ❌ Marketing emails (unless you opt in separately)
• ❌ Selling or sharing your email
• ❌ Tracking your email activity

No Tracking Pixels

Our magic link emails don’t include tracking pixels or read receipts. We don’t know if you opened the email—only if you clicked the link.

Data Minimization

We store only what’s necessary:

Data	Purpose	Retention
Email address	Identify your account	Until you delete account
Magic link token	One-time authentication	15 minutes then deleted
JWT token	Session authentication	30 days or until sign out
Favorites list	Sync across devices	Until you delete favorites

Rate Limiting

To prevent abuse, magic links are rate-limited:

• 3 requests per 15 minutes per email address
• 10 requests per hour per IP address

If you exceed this, you’ll see a message: “Too many requests. Please wait 15 minutes.”

This prevents:

• Spam attacks on email addresses
• Brute force token guessing
• API abuse

Tip

If you’re legitimately locked out, wait 15 minutes and try again. The limit is generous for normal use.

Comparison to Other Methods

vs. Traditional Passwords

Aspect	Passwords	Magic Links
Security	Weak if reused or simple	Strong cryptographic tokens
User friction	High (create, remember, reset)	Low (just click link)
Mobile UX	Poor (typing complex passwords)	Excellent (tap link)
Breach risk	High (password hashes leaked)	Low (no stored secrets)
Phishing risk	High (fake login pages)	Low (link contains auth)

vs. OAuth (Google/Facebook Login)

Aspect	OAuth	Magic Links
Privacy	Shares data with third party	No third party involved
Dependency	Requires external account	Just need email
Complexity	Multiple redirects	Single email click
Trust	”Why does this need my Google?"	"Just my email? Cool.”

vs. SMS Codes

Aspect	SMS Codes	Magic Links
Reliability	SMS can be delayed	Email is more reliable
Cost	SMS costs money	Email is free
Accessibility	Requires phone number	Works with any email
Security	SIM swapping attacks	Email account compromise only

Best Practices for Users

1. Use a reliable email — Gmail, Outlook, etc. with good uptime
2. Check spam folder — Magic links sometimes get filtered
3. Click quickly — Links expire in 15 minutes
4. Don’t share links — They authenticate as you
5. Sign out on shared devices — Clears session token

Best Practices for Brokerages

1. Monitor email delivery — Ensure magic links arrive promptly
2. Whitelist sender — Work with email providers to avoid spam filters
3. Clear email copy — Make it obvious what the link does
4. Brand emails — Use your logo and colors for trust
5. Respect privacy — Don’t use auth emails for marketing

Technical Implementation

For developers integrating magic link auth:

// Request magic link
async function requestMagicLink(email) {
  const response = await fetch('/auth/magic-link', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email })
  });
  return response.json();
}

// Verify magic link token
async function verifyToken(token) {
  const response = await fetch(`/auth/verify?token=${token}`);
  const data = await response.json();

  if (data.jwt) {
    localStorage.setItem('idx_auth_token', data.jwt);
    localStorage.setItem('idx_auth_email', data.email);
  }

  return data;
}

// Check auth state
function isAuthenticated() {
  const token = localStorage.getItem('idx_auth_token');
  if (!token) return false;

  // Decode JWT and check expiration
  const payload = JSON.parse(atob(token.split('.')[1]));
  return payload.exp > Date.now() / 1000;
}

API Available

See the Favorites API documentation for complete authentication endpoints.

Future Enhancements

We’re exploring additional passwordless options:

• WebAuthn/passkeys — Biometric authentication (fingerprint, Face ID)
• Social OAuth — Optional Google/Facebook login
• Remember this device — Extended sessions on trusted devices

These will be optional additions—magic links will always be the primary method.

Related Features

• Syncing Favorites — Practical guide to using magic links
• Favorites API — Technical API documentation
• Client Registration — How lead capture works