Skip to main content

​
Magic Links

Magic links provide passwordless authentication via email. Users enter their email address, receive a one-time link, and clicking it signs them in.

​
How It Works

1

Request

User submits their email via POST /api/v1/auth/magic/request.
2

Token Generation

The backend generates a secure random token and stores it in Redis with a time-to-live (default: 10 minutes).
3

Email Delivery

A magic link email is sent via Resend containing a verification URL with the token.
4

Verification

When the user clicks the link, GET /api/v1/auth/magic/verify validates the token against Redis.
5

Authentication

If valid, the user is created or matched by email, a session is created, and the token is deleted from Redis (one-time use).

​
Configuration

VariableDefaultDescription
RESEND_API_KEY(empty)Resend API key for sending emails. If unset, emails are logged to stdout.
RESEND_FROM_EMAIL[email protected]Sender email address
MAGIC_LINK_EXPIRY_MINUTES10Token expiry time in minutes

​
Development Mode

When RESEND_API_KEY is not set, magic link emails are logged to stdout instead of sent. This makes local development easy — just check the server logs for the verification URL. 
INFO  Magic link for [email protected]: http://localhost:8080/api/v1/auth/magic/verify?token=abc123

​
Email Setup (Production)

For production, set up a Resend account:
  1. Sign up at resend.com
  2. Add and verify your sending domain
  3. Generate an API key
  4. Set RESEND_API_KEY and RESEND_FROM_EMAIL in your environment

​
Security

  • Token format validation — tokens are validated before Redis lookup to prevent injection
  • One-time use — tokens are deleted from Redis after successful verification
  • Time-limited — tokens expire after the configured duration
  • Email normalization — email addresses are lowercased and trimmed
  • Body size cap — request body size is limited to prevent abuse
  • Rate limiting — magic link requests are rate-limited (20 req/min per IP)