Setup
2
Add the plugin
lib/theauth.ts
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.How it works
- User submits their email to
POST /auth/magic-link/send. - theAuth generates a signed token and calls your
sendMagicLinkfunction with the email address, the raw token, and the full URL. - User clicks the link in their inbox.
- 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.
Endpoints
Send link
POST /auth/magic-link/send
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 fromx-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.
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.
Related
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.