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; consume must come from the same network. A forwarded link that opens in a different network refuses to log in.
• 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 TOTP enrolled, the response is an MFA challenge ({ mfa_required: true, challenge_token }) instead of a session — complete it at /v1/totp/verify-signin.
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.