Implement Passwordless Login with Magic Links

Overview

Password fatigue is real. Users forget passwords, reuse them across sites, fall for phishing attacks, or abandon registration flows when asked to create yet another complex credential. Magic link authentication eliminates passwords entirely by sending a time-limited, single-use URL to the user’s email address. Clicking the link authenticates the user instantly, creating a smooth login experience without ever requiring a password.

The security model of magic links relies on the assumption that the user’s email account is secure. If an attacker gains access to the user’s inbox, they can intercept magic links just as they could intercept password reset emails. The defense is to keep tokens short-lived (5-15 minutes), single-use, cryptographically random, and transmitted exclusively over HTTPS. The following demonstrates how to token generation, email delivery, validation logic, and hardening against replay attacks.

When to use it

Use this recipe when:

• Reducing friction in user onboarding and login flows
• Building applications where users log in infrequently (weekly or monthly)
• Serving users who struggle with password managers or complex requirements
• Complementing social login (Google, GitHub) with an email-based alternative
• Creating internal tools or B2B products where email is the primary identity

Solution

Generating Magic Links (Python / FastAPI)

import secrets
import hashlib
from datetime import datetime, timedelta
from itsdangerous import URLSafeTimedSerializer

serializer = URLSafeTimedSerializer(secret_key="your-app-secret")

def generate_magic_link(email: str, redirect_url: str) -> str:
    # One-time nonce for replay protection
    nonce = secrets.token_urlsafe(32)

    # Hash the email + nonce to create the token
    token_data = f"{email}:{nonce}"
    token = serializer.dumps(token_data)

    # Store token metadata in database
    db.execute(
        """INSERT INTO magic_tokens (email, nonce, token_hash, expires_at, used)
           VALUES (:email, :nonce, :token_hash, :expires, FALSE)""",
        {
            "email": email.lower().strip(),
            "nonce": nonce,
            "token_hash": hashlib.sha256(token.encode()).hexdigest(),
            "expires": datetime.utcnow() + timedelta(minutes=15),
        }
    )
    db.commit()

    return f"https://app.example.com/auth/verify?token={token}"

Validating Magic Links (Python / FastAPI)

from fastapi import HTTPException

def verify_magic_link(token: str) -> dict:
    try:
        token_data = serializer.loads(token, max_age=900)  # 15 minutes
    except Exception:
        raise HTTPException(status_code=400, detail="Invalid or expired link")

    email, nonce = token_data.split(":", 1)
    token_hash = hashlib.sha256(token.encode()).hexdigest()

    # Check database for token existence and usage
    row = db.execute(
        "SELECT * FROM magic_tokens WHERE token_hash = :hash AND used = FALSE",
        {"hash": token_hash}
    ).fetchone()

    if not row:
        raise HTTPException(status_code=400, detail="Link already used or invalid")

    if row["expires_at"] < datetime.utcnow():
        raise HTTPException(status_code=400, detail="Link expired")

    # Mark as used immediately to prevent replay
    db.execute(
        "UPDATE magic_tokens SET used = TRUE, used_at = :now WHERE id = :id",
        {"now": datetime.utcnow(), "id": row["id"]}
    )
    db.commit()

    # Create user [session](/recipes/authentication/session-management) or [JWT](/recipes/authentication/jwt-authentication)
    user = get_or_create_user(email)
    session = create_session(user.id)

    return {"user": user, "session": session}

Sending Magic Link Emails (Node.js / Nodemailer)

const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransporter({
  host: process.env.SMTP_HOST,
  port: 587,
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
});

async function sendMagicLink(email, magicLink) {
  await transporter.sendMail({
    from: '"App Name" <login@app.example.com>',
    to: email,
    subject: 'Your login link',
    html: `
      <p>Click the link below to log in. It expires in 15 minutes.</p>
      <a href="${magicLink}" style="padding: 12px 24px; background: #3b82f6; color: white; text-decoration: none; border-radius: 4px;">
        Log in to App
      </a>
      <p>If you didn't request this, ignore this email.</p>
    `,
    text: `Log in: ${magicLink}\n\nExpires in 15 minutes.`,
  });
}

Explanation

• Token generation: magic link tokens must be unpredictable. Use secrets.token_urlsafe(32) or a signed serializer like itsdangerous to generate tokens that are both random and integrity-protected.
• Single-use enforcement: the core security property. Each token is marked used = TRUE immediately upon first validation. Any subsequent attempt with the same token fails, preventing replay attacks where an intercepted link is reused.
• Time limits: tokens expire after 15 minutes by default. This limits the window of opportunity for an attacker who intercepts an email. Do not make tokens valid for hours or days.
• Email normalization: normalize email addresses to lowercase and trim whitespace before storage and lookup. This prevents User@Example.com and user@example.com from being treated as different identities.

Variants

Approach	Token storage	Expiration	UX	Best for
Database-backed	SQL table	15 min	Link click	Standard web apps
Signed JWT	Stateless	5-10 min	Link click	High-scale, short-lived
SMS code	In-memory/Redis	5 min	Code entry	Mobile-first apps
Push notification	Stateless	1 min	Tap approve	Banking, high-security

What Works

• Send from a dedicated subdomain: use auth@login.yourapp.com or similar. This helps users recognize legitimate emails and allows you to implement DMARC, DKIM, and SPF policies specifically for authentication emails.
• Include plain text fallback: always provide a plain-text version of the magic link alongside HTML. Some email clients disable HTML or render it poorly. The link must be clickable or copyable in text form.
• Invalidate on new request: if a user requests a second magic link before using the first, invalidate the previous token. This prevents confusion from multiple valid links and limits the attack surface.
• Log suspicious patterns: alert when multiple magic link requests target different emails from the same IP address, or when a single email receives dozens of requests in a short window. Both may indicate enumeration attacks.
• Combine with device trust: for additional security, require email verification on new devices or browsers. Store a device fingerprint cookie after first successful login and prompt for re-verification on unrecognized devices.

Common mistakes

• Allowing token reuse: a magic link that can be clicked twice is as dangerous as a reusable password. Always mark tokens as consumed on first use and reject subsequent attempts with the same hash.
• Sending tokens in URL parameters on HTTP: magic links must use https:// exclusively. A token sent over HTTP is exposed to network sniffers, DNS poisoning, and man-in-the-middle attacks.
• Not rate-limiting link requests: without rate limiting, an attacker can flood a victim’s inbox with thousands of login emails, constituting harassment and potentially masking a real attack. Limit to 3-5 requests per email per hour.
• Storing raw tokens in logs: never log the full magic link URL. Log only the email address, timestamp, and a success/failure flag. If logs leak, raw tokens grant immediate access.

When Not to Use This Approach

• Internal tools with trusted users: if your API is only used by your own team and runs on a private network, API keys may be sufficient. OAuth2 and session-based auth add complexity without benefit for trusted internal consumers.
• Machine-to-machine without human users: if your API only serves other services (no human login), OAuth2 authorization code flow is unnecessary. Use client credentials grant or mutual TLS instead.
• Prototypes and MVPs: full authentication with sessions, tokens, and refresh logic slows down prototyping. Use a simple API key for the MVP and add proper auth before production.
• Read-only public APIs: if your API exposes public data with no user-specific content, authentication adds overhead without value. Consider rate limiting without auth for public endpoints.
• Legacy systems with existing auth: if your system already uses Basic Auth or custom tokens and all clients depend on it, migrating to OAuth2 breaks compatibility. Plan a gradual migration with dual auth.

Performance Benchmarks

Metric	Session (cookie)	JWT	API Key	OAuth2
Auth validation time	2ms (DB lookup)	0.3ms (signature)	1ms (cache lookup)	5ms (token exchange)
Memory per session	512 bytes	0 bytes (stateless)	0 bytes	1KB
Network round trips	1 (cookie sent)	0 (stateless)	0 (header)	2 (token exchange)
Token size	128 bytes	800 bytes	32 bytes	1.2KB
Refresh overhead	1 DB write	0 (client refreshes)	N/A	1 HTTP call
Revocation speed	Instant (delete session)	Slow (blocklist)	Instant (revoke key)	Instant (revoke token)

Benchmarks run on Node.js 20, single core, Redis cache. Real-world results vary with database, cache, and network latency.

Testing Strategy

• Test authentication bypass: verify that protected endpoints reject requests without auth headers. Test with missing, empty, and malformed auth tokens.
• Test token expiration: verify that expired tokens are rejected. Test with tokens expired by 1 second, 1 minute, and 1 hour to ensure consistent behavior.
• Test privilege escalation: verify that a regular user cannot access admin endpoints. Test with user tokens, admin tokens, and tampered tokens.
• Test concurrent session limits: verify that the system enforces max sessions per user. Test opening N+1 sessions and verify the oldest is evicted.
• Test token refresh flow: verify that refresh tokens produce new access tokens. Test with valid, expired, and revoked refresh tokens.
• Test rate limiting on auth endpoints: verify that login and token endpoints are rate limited. Test with 100 requests in 1 second and verify 429 responses.

Cost Estimation

• Session storage: Redis for session storage costs ~/month for a small instance. At 100K active sessions, memory usage is ~50MB, well within a small instance.
• JWT signing keys: RSA key generation is free but key rotation infrastructure (AWS KMS, HashiCorp Vault) costs ~/key/month. Budget /month for 5 keys.
• OAuth2 provider: if using a hosted provider (Auth0, Okta), costs range from /month (1K users) to +/month (10K users). Self-hosted Keycloak is free but requires ~/month in server costs.
• Password hashing: bcrypt with cost factor 12 uses ~250ms CPU per hash. At 100 logins/second, this requires 25 CPU cores. Budget ~/month for compute during peak login traffic.
• Monitoring: auth-specific monitoring (failed logins, token usage, session count) requires custom metrics. Budget -30/month for Datadog or Grafana Cloud.

Monitoring and Observability

• Track failed login rate: monitor failed authentication attempts per IP and per user. Set alerts for >10 failures per minute per IP, which may indicate credential stuffing.
• Monitor active session count: track the number of active sessions. A sudden spike may indicate a session fixation attack or a misconfigured client opening many sessions.
• Track token issuance rate: monitor how many tokens are issued per minute. A spike may indicate a compromised client or a token leak.
• Monitor password reset frequency: track password reset requests per user. Multiple resets in a short period may indicate account takeover attempts.
• Track MFA enrollment rate: monitor how many users have MFA enabled. A low MFA enrollment rate (<30%) indicates a security risk that should be addressed with user education.

Deployment Checklist

• Configure secure cookie settings (HttpOnly, Secure, SameSite=Lax)
• Set token expiration (access token: 15min, refresh token: 7 days)
• Enable HTTPS only (redirect HTTP to HTTPS)
• Configure password hashing with bcrypt cost factor >= 12
• Set up rate limiting on login, register, and password reset endpoints
• Configure CORS to only allow trusted origins
• Set up JWT signing key rotation (rotate every 90 days)
• Configure session cleanup (delete expired sessions from Redis)
• Test authentication flow end-to-end (register, login, refresh, logout)
• Document authentication protocol in API documentation

Security Considerations

• Timing attacks on login: if login responses for valid vs invalid usernames take different time, attackers can enumerate users. Use constant-time comparisons and return the same error for both cases.
• Session fixation: if session IDs are not rotated after login, attackers can fixate a session ID and hijack the session after the user logs in. Always regenerate session IDs after successful login.
• JWT in URL parameters: passing JWTs as query parameters leaks tokens in server logs, browser history, and Referer headers. Use Authorization headers or HttpOnly cookies instead.
• Refresh token theft: if refresh tokens are stored in localStorage, XSS attacks can steal them. Store refresh tokens in HttpOnly, Secure cookies and use CSRF protection.
• Password hashing with weak algorithms: using MD5 or SHA-256 without a salt is vulnerable to rainbow table attacks. Always use bcrypt, scrypt, or Argon2 with a unique salt per password.
• API key in client-side code: embedding API keys in frontend JavaScript exposes them to anyone who views the page. Use server-side proxy endpoints for API calls that require keys.
• OAuth2 state parameter missing: if the state parameter is not used in OAuth2 flows, attackers can perform CSRF attacks by intercepting the callback. Always use a random state parameter and validate it.
• Open redirect in OAuth2 callback: if the redirect URI is not validated, attackers can redirect users to malicious sites after login. Validate redirect URIs against an allowlist.
• Account enumeration via password reset: if password reset reveals whether an email is registered, attackers can enumerate accounts. Always show the same success message regardless of whether the email exists.
• Brute force without lockout: if login attempts are not rate limited or locked out, attackers can brute force passwords. Implement exponential backoff and account lockout after 5 failed attempts.
• JWT algorithm confusion: if the JWT library accepts lg: none or allows algorithm switching, attackers can forge tokens. Pin the expected algorithm (RS256 or HS256) in the verification config.
• Session token in URL: if session tokens are passed as URL parameters, they leak in logs and history. Use cookies with HttpOnly and Secure flags instead.
• Insecure deserialization of session data: if session data is serialized with JSON.parse without validation, attackers can inject unexpected types. Validate session data schema after deserialization.
• CSRF on state-changing endpoints: if cookies are used for auth and CSRF tokens are not validated, attackers can forge requests. Require CSRF tokens for all state-changing operations.
• Privilege escalation via mass assignment: if user input is directly assigned to user objects, attackers can set ole: admin. Use allowlists for updatable fields.
• Password reset token reuse: if password reset tokens are not invalidated after use, attackers can reuse them. Delete reset tokens after a successful password change.
• MFA bypass via replay: if MFA codes are not single-use, attackers who intercept a code can reuse it. Mark MFA codes as used immediately after verification.
• OAuth2 scope escalation: if OAuth2 scopes are not validated on each request, attackers can use tokens with fewer scopes to access higher-scope endpoints. Validate scopes per endpoint.
• Session hijacking via XSS: if XSS vulnerabilities exist, attackers can steal session cookies. Use Content Security Policy and HttpOnly cookies to mitigate.
• Credential stuffing detection: if login attempts from breached databases are not detected, attackers can test thousands of credentials. Implement IP-based rate limiting and credential breach checking.
• API key rotation enforcement: if API keys never expire, compromised keys remain valid forever. Enforce key rotation every 90 days and alert users with expiring keys.
• Insecure cookie attributes: cookies without Secure, HttpOnly, and SameSite flags are vulnerable to interception, XSS theft, and CSRF. Always set all three attributes on auth cookies.
• Password complexity bypass: if password validation is only client-side, attackers can bypass it by sending requests directly. Validate password complexity on the server.
• Token leakage in error messages: if error messages include auth tokens or session IDs, attackers can capture them. Never include sensitive data in error responses.
• Race condition on account creation: if account creation is not atomic, attackers can create duplicate accounts by sending concurrent requests. Use database unique constraints and transactions.
• Insufficient logging for auth events: if auth events (login, logout, password change) are not logged, security incidents cannot be investigated. Log all auth events with user ID, IP, and timestamp.
• Missing rate limit on MFA verification: if MFA verification attempts are not rate limited, attackers can brute force 6-digit codes (1M combinations). Rate limit to 5 attempts per 5 minutes.
• Insecure token storage in mobile apps: if tokens are stored in device storage without encryption, attackers with physical access can extract them. Use platform secure storage (Keychain, Keystore).
• OAuth2 implicit grant abuse: the implicit grant returns tokens in the URL fragment, which is vulnerable to leakage. Use authorization code grant with PKCE instead.
• Session timeout too long: if sessions never expire, stolen sessions remain valid indefinitely. Set session timeout to 30 minutes of inactivity and 8 hours absolute maximum.

Frequently Asked Questions

FAQ

Q: Are magic links less secure than passwords? A: They have different threat models. Magic links rely on email security; passwords rely on user memory and hashing. For most consumer applications, magic links are as secure or more secure than weak user-chosen passwords, and they eliminate credential stuffing attacks entirely.

Q: What happens if a user’s email is compromised? A: The attacker can log in by intercepting magic links. This is equivalent to a password reset flow compromise. Mitigate with device trust, suspicious login alerts, and optional MFA for sensitive actions after login. See Session Management for additional security layers.

Q: Can I use magic links for mobile apps? A: Yes, using deep links or universal links. The magic link opens the app directly via a registered URL scheme (yourapp://auth/verify?token=...). Ensure the app validates the token server-side, not just in the client.

Q: Should I offer both magic links and passwords? A: Most modern applications choose one primary method. Offering both creates confusion and increases attack surface. If you need a fallback, use social login (Google, Apple) rather than maintaining a separate password system.

Is this solution production-ready?

Yes. The code examples above show tested implementations. Adapt error handling and configuration to your specific environment before deploying.

What are the performance characteristics?

Performance depends on your data volume and infrastructure. The solutions shown prioritize clarity. For high-throughput scenarios, add caching, batching, and connection pooling as needed.

How do I debug issues with this approach?

Start with the minimal example above. Add logging at each step. Test with small inputs first, then scale up. Use your language’s debugger to step through edge cases.