Auth API reference

Auth API · Consumer-Auth

post/{app_slug}/v1/auth/email/startAuth

Start 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*string

Slug of the app.

Request body

email*string · email

The 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 · uri

Only 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 · uri

Overrides 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_tokenstring

The 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 · uuid

Optional tenant to activate on the session, same as `tenant_id` on `/auth/signin`.

Response · 200 Flow started. Same body whatever the address.

flow_id*string

Identifies 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-time

When the code and link stop working (ISO 8601).

delivery*object

What the email carries: `code`, `link`, or `code_and_link`. Use it to decide whether to show a code box.

retry_after_seconds*number

Seconds 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"
}

Response

{
  "flow_id": "pwf_3q2-7wJcR1oPq0sZ1yG5x1u4k5mXo0Vd8V9mT7Xc1aE",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "delivery": {},
  "retry_after_seconds": 30
}