/{app_slug}/v1/auth/email/startAuthStart a passwordless email sign-in (magic link or code)
Emails a sign-in link and/or a 6-digit code to `email`, per the app's `passwordless_email` settings. Sign-up and sign-in are the same flow: an address with no account gets one when it verifies, if the app allows sign-up through this flow (`passwordless_email.allow_signup`, `signup_enabled`, the email-domain allowlist, and a Platform API Key when the app sets `signup_requires_pak`). **No account enumeration.** The response is identical whether the address has an account, may get one, or neither. An address that can neither sign in nor sign up gets no email and a flow that can never be completed; the caller cannot tell the difference. Keep the returned `flow_id` in the browser that called this (it binds the link to that browser) and finish with `POST /auth/email/verify`. Codes and links are single-use and expire after `passwordless_email.ttl_minutes` (default 10). Limits, all checked before the address is looked up: one email per address every 30 seconds and 5 per hour, 30 starts per client IP per hour, 1,000 per app per hour (429 `PASSWORDLESS_RATE_LIMITED` with `details.retry_after_seconds`). When the app has bot protection on, every start needs a `bot_protection_token`.
Path parameters
app_slug*stringSlug of the app.
Request body
email*string · emailThe address to sign in (or sign up) with. The response is the same whether or not it has an account.
Example: "ada@example.com"
return_tostring · uriOnly for a hosted hand-off: where to send the person once they are signed in, with `?heimdall_code=<code>` your backend exchanges at `POST /{app_slug}/v1/auth/oauth/exchange`. Its origin must be in `allowed_redirect_origins`. Leave it out when your own page calls `/auth/email/verify` and takes the tokens itself.
Example: "https://app.example.com/auth/callback"
link_urlstring · uriOverrides the app's `passwordless_email.link_url` for this email: the page the magic link opens (it receives `?token=`). Its origin must be in `allowed_redirect_origins`, or be Auth's hosted page.
Example: "https://app.example.com/sign-in/email"
bot_protection_tokenstringThe CAPTCHA widget response, required when the app has bot protection on. Every start can send an email, so it is checked on every start, sign-in and sign-up alike.
tenant_idstring · uuidOptional tenant to activate on the session, same as `tenant_id` on `/auth/signin`.
Response · 200 Flow started. Same body whatever the address.
flow_id*stringIdentifies this sign-in to the browser that started it. Keep it (memory, session storage or an httpOnly cookie) and send it with the code or the link token. Holding it is what lets a magic link finish in this browser. Single flow, never reused.
Example: "pwf_3q2-7wJcR1oPq0sZ1yG5x1u4k5mXo0Vd8V9mT7Xc1aE"
expires_at*string · date-timeWhen the code and link stop working (ISO 8601).
delivery*objectWhat the email carries: `code`, `link`, or `code_and_link`. Use it to decide whether to show a code box.
retry_after_seconds*numberSeconds before another email to this address can be requested.
Example: 30
Example
Request
POST https://api.auth.productcraft.co/{app_slug}/v1/auth/email/start
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"email": "ada@example.com",
"return_to": "https://app.example.com/auth/callback",
"link_url": "https://app.example.com/sign-in/email",
"bot_protection_token": "string",
"tenant_id": "00000000-0000-0000-0000-000000000000"
}import { Auth } from "@productcraft/auth";
// Admin routes read PRODUCTCRAFT_API_KEY; consumer routes need no key
const auth = new Auth();
const consumerEmailSignInStart = await auth.consumer("my-app").email.start({ email: "ada@example.com" });auth.consumer(…).email.start(params, options?): Auth.ConsumerEmailSignInStart
Response
{
"flow_id": "pwf_3q2-7wJcR1oPq0sZ1yG5x1u4k5mXo0Vd8V9mT7Xc1aE",
"expires_at": "2026-01-01T00:00:00.000Z",
"delivery": {},
"retry_after_seconds": 30
}