Magic link

Magic links let users sign in by clicking a link sent to their email. No password needed. The link is a signed, single-use token that expires after a configurable window.

Setup

pnpm add kavachos

import { createKavach } from 'kavachos';
import { magicLink } from 'kavachos/plugins/magic-link'; 

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://auth.example.com',
  plugins: [
    magicLink({ 
      onSendLink: async (email, url) => { 
        await resend.emails.send({
          from: 'auth@example.com',
          to: email,
          subject: 'Your sign-in link',
          html: `<a href="${url}">Sign in to Example</a>. Link expires in 15 minutes.`,
        });
      }, 
    }), 
  ],
});

magicLink({
  redirectTo: '/dashboard', 
  onSendLink: async (email, url) => { /* ... */ },
}),

How it works

1. User submits their email to POST /auth/magic-link/send.
2. KavachOS generates a signed token and calls your onSendLink function with the email address and the full URL.
3. User clicks the link in their inbox.
4. KavachOS validates the token, creates or retrieves the user, sets a session cookie, and redirects.

If the email belongs to an existing account, the same user ID is returned. If it is new, an account is created automatically.

Endpoints

Send link

POST /auth/magic-link/send

await fetch('/auth/magic-link/send', { 
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com' }),
});

The response is always 200 to prevent email enumeration. Attach a redirectTo in the body to override the default redirect for this request:

body: JSON.stringify({ email: 'user@example.com', redirectTo: '/onboarding' }),

Verify token

GET /auth/magic-link/verify?token=<token>

KavachOS handles this automatically when the user clicks the link. On success, the user is redirected. On failure (expired or already-used token), a 400 is returned.

Rate limiting

Requests to /auth/magic-link/send are limited to 5 per minute per IP address. Requests that exceed this return 429 Too Many Requests. Build a cooldown timer into your UI so users know when they can retry.

Options