Back to docsRecipe

Recipe: Magic-link auth design

A stateless, token-based authentication flow that replaces passwords with single-use links delivered over email. Built for Meridian's licensing dashboard.

Flow overview

  1. 1User submits email via the login form. No password field exists.
  2. 2Server generates a signed JWT containing the email, a nonce, and a 10-minute expiry. The token is embedded in a link and emailed.
  3. 3User clicks the link. The callback route verifies the JWT signature and expiry, then issues a session cookie.
  4. 4Subsequent requests carry the session cookie. No refresh tokens needed — re-authentication is a new magic link.

Security properties

  • •Single-use enforcement via nonce store in Upstash KV with TTL matching JWT expiry.
  • •HMAC-SHA256 signing with a 256-bit secret rotated on deploy.
  • •Rate-limited email dispatch: 3 links per email per 15-minute window.
  • •No user enumeration — identical response whether email exists or not.

Endpoints

MethodPathPurpose
POST/api/auth/loginAccepts email, triggers magic link
GET/api/auth/callbackValidates token, sets session
POST/api/auth/logoutClears session cookie