Skip to main content
Magic links let users sign in by clicking a link sent to their email. No password needed. The link carries a random single-use token that expires after a configurable window.

Setup

1

Install

2

Add the plugin

lib/theauth.ts
The plugin throws at startup unless auth.session is configured, because it issues a session when the link is verified. auth.session.secret must be at least 32 characters. appUrl is prepended to the callback path to build the link, so it must point at where the verify endpoint is reachable (the adapter mount path, /api/theauth by default).You can also skip the plugin and pass the same options as a top-level magicLink key to createTheAuth. That exposes theauth.magicLink (sendLink, verify, handleRequest), which is null when the config key is absent or auth.session is not set.
3

Handle the callback route

Magic links point at appUrl + callbackPath + ?token=.... The plugin registers GET /auth/magic-link/verify, which matches the default callbackPath. Leave callbackPath unchanged when you use the plugin.

How it works

  1. User submits their email to POST /auth/magic-link/send.
  2. theAuth generates a signed token and calls your sendMagicLink function with the email address, the raw token, and the full URL.
  3. User clicks the link in their inbox.
  4. theAuth validates the token, creates or retrieves the user, and returns the user and a session token as JSON. It does not set a cookie or redirect, so your app stores the session token (for example in a cookie) and navigates the user.
If the email belongs to an existing account, the same user ID is returned. If it is new, an account is created automatically.

Endpoints

POST /auth/magic-link/send
The email is trimmed and lowercased. A successful response is 200 with { "sent": true }. A missing email returns 400. A user record is created for the address when the link is issued, so an unknown email gets an account.

Verify token

GET /auth/magic-link/verify?token=<token> On success, returns 200 with { user: { id, email }, session: { token, expiresAt } }. A missing token returns 400, and an invalid, expired, or already-used token returns 401.

Rate limiting

The send endpoint is limited to 5 requests per minute per IP address (taken from x-forwarded-for or x-real-ip). Requests over the limit return 429 Too Many Requests with a Retry-After header. Build a cooldown timer into your UI so users know when they can retry.
Magic links are single-use. Clicking an expired or already-used link returns a 401. Show the user a “resend” option in your UI.

Options

Redeeming a link or code marks the address verified. The cleanup stops account pre-hijacking: someone who registered the victim’s address first would otherwise keep the password they set after the victim signs in.

Email OTP

Numeric code via email, useful when links are awkward to click.

Email and password

Password-based auth that can run alongside magic links.

Passkey

WebAuthn biometrics as an alternative passwordless method.

Authentication overview

All sign-in methods available in theAuth.
Last modified on October 19, 2026