Auth guides
15 · Email sign-in

Sign in with a link or a code.

People type their email and get a sign-in link, a 6-digit code, or both. No password to set or forget. New addresses get an account the same way, if you allow sign-ups.


1

Switch it on

In the console, open Auth, pick your app, then Settings, Email sign-in.

  • The email contains: a link and a code (the default), a link only, or a code only. A code works on any device; a link is one click.
  • Links open: Auth's hosted sign-in page, or a page in your app. Your own page must be on one of the app's allowed redirect origins.
  • Links and codes last: 5 to 15 minutes (10 by default). Each one works once.
  • Create accounts for new addresses: on by default, and only while sign-ups are allowed for the app.
  • Links only work in the browser that asked: on by default. See step 4.

The email goes out through Mail with the app's Email sign-in template. If none is chosen, the card offers Create the default template, which adds auth-sign-in to your Mail templates. Edit it there like any other template; it gets appName, code, signInUrl and expiresInMinutes.

The same settings are passwordless_email on PATCH /v1/apps/{app_id}/auth-config, and the template is sign_in_template_name on the notification settings.


2

The quickest way: the hosted page

Link to it with a return_to on your site. Nothing else to build.

Your sign-in page
<a href="https://auth.productcraft.co/a/<your-app-slug>/sign-in?return_to=https%3A%2F%2Fapp.acme.com%2Flogin%2Fdone">
  Sign in with email
</a>

The page asks for the email, shows a code box when the email has a code, and handles the link. When the person is signed in they come back to your return_to with ?heimdall_code=…, exactly like a Google or GitHub sign-in, and your backend swaps it for tokens:

Your backend: code to tokens
import { Auth, AuthenticationError } from "@productcraft/auth";

const consumer = new Auth().consumer("acme");

async function completeProviderSignIn(code: string) {
  try {
    // code: the heimdall_code query value
    const { access_token, refresh_token, expires_in } =
      await consumer.exchangeProviderCode({ code });
    // Drop into your session cookie / store as you'd handle a sign-in.
    return { access_token, refresh_token, expires_in };
  } catch (err) {
    // 401: unknown, expired or already used
    if (err instanceof AuthenticationError) return null;
    throw err;
  }
}

If the person has a two-step factor, the exchange answers with result: "mfa_required" and an mfa_token instead of tokens: finish it with /auth/mfa/verify as after a password sign-in. When the app has bot protection on, the page shows the CAPTCHA itself.


3

Or build it into your own page

Two calls. Start with the address, then finish with the code or the link.

Node: @productcraft/auth
import { Auth, AuthenticationError } from "@productcraft/auth";

const consumer = new Auth().consumer("acme");

// 1. Your sign-in page posts the address. Same answer for every address.
export async function startEmailSignIn(email: string) {
  const { flow_id, delivery } = await consumer.email.start({ email });
  return { flow_id, showCodeBox: delivery !== "link" }; // keep flow_id in this browser
}

// 2. Finish with the 6-digit code, or with the link's ?token=
export async function finishEmailSignIn(flow_id: string, input: { code?: string; token?: string }) {
  try {
    const result = await consumer.email.verify({ flow_id, ...input });
    // "session" carries access_token and refresh_token; "mfa_required" and
    // "mfa_enrollment_required" continue with consumer.mfa.*
    return "result" in result ? result : null;
  } catch (err) {
    // 401 PASSWORDLESS_CODE_INVALID: wrong, used or expired
    if (err instanceof AuthenticationError) return null;
    throw err;
  }
}

The same two calls over HTTP:

1. Start
curl -X POST https://api.auth.productcraft.co/<your-app-slug>/v1/auth/email/start \
  -H 'Content-Type: application/json' \
  -d '{ "email": "ada@example.com" }'

# 200, the same for every address:
{
  "flow_id": "pwf_3q2-7wJcR1oPq0sZ1yG5x1u4k5mXo0Vd8V9mT7Xc1aE",
  "expires_at": "2026-11-17T12:10:00.000Z",
  "delivery": "code_and_link",
  "retry_after_seconds": 30
}

Keep flow_id in the browser that asked, in memory, session storage or an httpOnly cookie. Show a code box when delivery includes a code.

2a. Finish with the code
curl -X POST https://api.auth.productcraft.co/<your-app-slug>/v1/auth/email/verify \
  -H 'Content-Type: application/json' \
  -d '{ "flow_id": "pwf_3q2-…", "code": "482913" }'

# 200: the same results as /auth/signin
{ "result": "session", "access_token": "eyJ…", "refresh_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600 }
2b. Finish with the link
# Your link page was opened as https://app.acme.com/sign-in/email?token=pwl_…
curl -X POST https://api.auth.productcraft.co/<your-app-slug>/v1/auth/email/verify \
  -H 'Content-Type: application/json' \
  -d '{ "flow_id": "pwf_3q2-…", "token": "pwl_…" }'

Verify answers like /auth/signin: a session, an MFA challenge when the person holds a factor, or an enrolment demand when your app requires MFA. The access token's amr is ["email", "otp"] after a code and ["email", "link"] after a link. The email is marked verified, and a new account gets user.signup before user.signin, both with method.


4

What keeps it safe

All of it is on by default.

  • Nobody learns who has an account. Start answers the same for every address. An address that cannot sign in or sign up gets no email, and a flow that can never be finished.
  • One use, short life. A code or link works once, for the minutes you set. Five wrong codes end the flow; every failure is the same 401 PASSWORDLESS_CODE_INVALID.
  • Links stay in the browser that asked. Opened anywhere else (a forwarded email, a phone), verify answers 409 PASSWORDLESS_LINK_OTHER_BROWSER without using the link, and details.code_available says whether the person can type the code from the same email instead.
  • Send limits. One email per address every 30 seconds and 5 an hour, 30 starts per client IP an hour, 1,000 per app an hour: 429 PASSWORDLESS_RATE_LIMITED with details.retry_after_seconds.
  • Your sign-up rules still apply. New addresses need sign-ups on, an allowed email domain, and an app key on the start call when the app takes sign-ups through your backend only. With bot protection on, every start needs a bot_protection_token, sign-in or sign-up.