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.
<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:
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.
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:
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.
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 }# 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_BROWSERwithout using the link, anddetails.code_availablesays 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_LIMITEDwithdetails.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.