Magic links

With a magic link, a user types only their email. Orvano emails them a link, and opening it signs them in, without a password. If the email has no account yet, the link creates one.

This guide starts from a finished quickstart running against Orvano on your machine; the link lands in the local inbox at http://localhost:8025. It uses the same kind of landing page as Email verification.

1. Send the link

account.createMagicLink needs no session, and answers the same way whether or not the email has an account.

JavaScript

await orvano.account.createMagicLink({ email, redirectUrl: `${location.origin}/sign-in.html` })

Next.js

'use server'
await (await orvano()).account.createMagicLink({ email, redirectUrl: `${appUrl}/auth/sign-in` })

Flutter

await orvano.account.createMagicLink(
  CreateMagicLinkRequest(email: email, redirectUrl: 'https://app.example.com/auth/sign-in'),
);

• Pass createUser: false to send links only to existing users. An unknown email then gets no email, and the same answer.
• The redirectUrl must be https on one of the project’s web platforms, or http on localhost. A magic link signs the user in, so it never goes to a custom app scheme. A Flutter app on iOS or Android needs https app links; during development, use email codes there instead.
• The link works once, for 15 minutes. Orvano sends at most one a minute, and five an hour, per email.

Open http://localhost:8025: you should see “Sign in to” your project with a Sign in button.

2. Sign in on the landing page

When the user selects Continue, finish the link:

JavaScript

const result = await orvano.client.redeemLink()
if (result?.isNewUser) showWelcome()

Next.js

'use client'
// app/auth/sign-in/page.tsx: the route handler sets the session cookies.
const result = await orvano.client.redeemLink()
router.push(result?.isNewUser ? '/welcome' : '/')

Flutter

final result = await orvano.client.handleLink(link);
if (result?.isNewUser ?? false) showWelcome();

The user is signed in, and their email is verified. isNewUser is true when the link created the account: a good moment to ask for their name with account.update. A new account made this way has no password; the user can set one within 10 minutes of signing in.

A used, expired, or replaced link gets invalid_email_token.

When an unverified account already exists

Someone could sign up with another person’s email and a password, before that person ever uses your app. When the real owner then signs in with a magic link, Orvano removes the unverified password and ends the other sessions, so the account is theirs alone.