Magic links — bound, brief, single-use.

What's actually in the link

• Token: a high-entropy token; only its hash is stored.
• TTL: 15 minutes — enough for a real user to read the email, short enough that a leaked link is dead before anyone gets to it.
• Single-use: on the first /v1/magic/consume hit, the token is marked used inside the same transaction that mints the session. Replay is a 400 Link already used.
• Network binding: the link is bound to the requesting network at send time (the IPv4 /24 or IPv6 /64); consume must come from the same network. A forwarded link that opens in a different network refuses to log in and stops working.
• Redirect allow-list: the optional redirect_uri is checked against the app's allowed_redirect_origins. Mismatch = the link refuses to consume.

Send

POST /v1/magic/send with { email, redirect_uri? }:

1. Rate limit per IP and per (app, email) — no email-bombing surface.
2. Mint the token, store only its hash bound to the requesting network and the redirect_uri, with a 15-minute TTL.
3. Send the email via your configured provider (Resend by default), using the per-app branding template.
4. Always answer success-shaped ({ ok: true }) — never reveal whether the email matched a real user. Audit row: signin.magic.sent.

Consume

POST /v1/magic/consume with { token }:

1. Find the token by its hash.
2. Check expiry — if expired, audit signin.magic.expired, 400 Invalid or expired link.
3. Check the network — if it doesn't match, audit signin.magic.ip_mismatch, 403 with a message telling the user to request a fresh link. The token is consumed regardless — the original link no longer works either, by design.
4. Mark the token used, mint the session inside the same transaction, audit signin.magic.ok.
5. If the account has a second factor, the response is an MFA challenge instead of a session. TOTP returns { mfa_required: true, challenge_token }; complete it at /v1/totp/verify-signin. Till Authenticator returns method: "push" with a push block; show its match_number and poll /v1/push/signin/poll.
6. If redirect_uri was bound and it passes the allow-list, return it in the response so your SDK can navigate the user there.

Hosted-login flow

On <slug>.tilldev.app the user clicks the magic-link button, types their email, gets the mail, clicks the link. The hosted-login page handles the consume side and redirects back to the app — your app never has to embed the magic-link UI itself.

React SDK

From the React SDK, hosting your own flow is two hooks:

// Send page
const { send, sent, pending } = useMagicLink()
await send({ email, redirect_uri: '/' })

// Callback page — read ?t= from the URL on mount
const { consume } = useMagicLink()
const r = await consume(token)
if (r.ok) router.push(r.redirect ?? '/')

When magic links are wrong

• High-value workflows (admin dashboards, treasury, anything regulated) should use passkeys or OAuth. Mailbox access shouldn't grant superuser.
• Shared inboxes (support@, team@) — the link works for whoever gets it first. Use email + password with MFA.