Building Flows from Scratch

A practical guide to the blank canvas. Covers how to think about node selection, how Web Page and its child nodes work together, which node to pick for each identity operation, and the most common mistakes to avoid.

The Three Questions

QUESTION 1

Does the user need to see something?

Use a Web Page node. Add input child nodes inside it to define the fields shown on that screen.

QUESTION 2

Does something need to happen in the background?

Use an action node: Auth, Create User, Send Email, Data Query, etc. These run server-side with no UI.

QUESTION 3

Where should the flow go depending on the result?

Wire the output edges. Every node emits at least true and false. Connect each to the appropriate next step.

Web Page Anatomy: Screens and Their Fields

Web Page is a container node. It renders a single screen. The child nodes you place inside it become the fields on that screen. The Output edge fires when the user submits the form.

Child node	What it renders	When to add it
Email	Email address input	Any flow that collects an email: login, registration, password reset
Password	Password input (masked)	Login (type: `login`) and registration/reset (type: `register`) flows
Phone	Phone number input	SMS OTP setup, phone-based login
OTP Input	One-time code field	Any second-factor screen after Send Email or Send SMS
User Name	Username text input	Username-based login flows
Choice	A set of selectable options	Letting users pick a second factor, consent choice, etc.
Consent Prompt	Consent checkbox with policy text	Capturing explicit consent at registration or login
Remember Me	"Keep me signed in" checkbox	Optional persistent-session toggle on the login screen

tip

All child nodes inside a single Web Page appear on the same rendered screen. If you need two screens (for example, email on screen 1 and OTP on screen 2), use two separate Web Page nodes wired in sequence.

Picking the Right Node

Authentication and identity

What you want to do	Node to use	What NOT to use (and why)
Verify a user's email + password	Auth	Identity Lookup: it resolves a profile but does NOT verify the password or issue a session
Look up a user's profile without authenticating	Identity Lookup	Auth: it authenticates immediately; use Identity Lookup when you need to inspect the profile first (required before MFA nodes)
Check if the user already has an active session	Has Session	NA
Authenticate via a social provider (Google, Facebook, etc.)	Social Auth node (Google, Facebook, Apple…)	NA
Authenticate via SAML	SAML Auth	NA

Account management

What you want to do	Node to use	What NOT to use (and why)
Create a new user account	Create User	NA
Check whether an account already exists	User Exists	NA
Update a user's profile field (e.g. new password)	Update User	NA
Delete a user	Delete User	NA

Communication

What you want to do	Node to use	What NOT to use (and why)
Send a password reset link	Send Suspended Email (type: `Forgot Password`)	Send Email: it sends the email but does NOT wait for the vtoken click or validate the reset token. The two-stage vtoken handshake only works with Send Suspended Email
Send an OTP or verification email	Send Email (type: `secondfactorauthentication` or `verification`)	Send Suspended Email: that node is specifically for flows where the user clicks a link in the email
Send an OTP via SMS	Send SMS	NA

MFA

What you want to do	Node to use	Implementation Notes
Check which MFA methods the user has registered	MFA Configured State	Always pair with Configure MFA on the failure output
Handle users who haven't set up MFA yet	Configure MFA (paired with MFA Configured State)	Leaving the MFA Configured State failure output unconnected: those users hit a dead end
Validate an OTP code	Verify Email/SMS OTP	NA
Validate an authenticator app code	Verify Authenticator	NA
Save a new phone number to the MFA profile	Update MFA Phone	Required after first-time SMS OTP setup; without it the phone number is not persisted

Logic and session control

What you want to do	Node to use	What NOT to use (and why)
Evaluate a condition (e.g. session count, profile field value)	Data Query	Script for simple comparisons: Data Query is configuration-only and requires no code
Run custom JavaScript	Script	NA
Route the flow based on user choice	Choice child inside Web Page, then wire its named outputs	NA
Enforce concurrent session limits	Data Query (`Sessions.Count`) + Force Logout	NA

How a Flow Starts: Four Common Entry Patterns

Start with Has Session.
True → skip the form → Success.
False → Web Page (Email + Password) → Auth.

Without Has Session, a logged-in user will always see the login form again.

REGISTRATION

Start directly with Web Page (Email + Password).
Output → User Exists.
True → loop back to form (duplicate error).
False → Create User.

Always check User Exists before Create User to prevent duplicate accounts.

PASSWORD RECOVERY

Start with Web Page (Email only).
Output → Send Suspended Email (type: Forgot Password).
True → Web Page (Password) → Update User.
False → loop back to form.

No session check needed: the user is unauthenticated by definition.

MFA LOGIN

Web Page (Email + Password) → Identity Lookup → MFA Configured State → method-specific path → Verify OTP → Success.

Never use Auth before MFA nodes. Identity Lookup resolves the profile without issuing a session token: which is exactly what MFA state needs to read.

Wiring Output Edges

Every node exposes output edges. Leaving one unconnected means users who hit that path are silently dropped.

Output type	What to connect it to
True	The next step in the happy path, or Success Final if the flow is complete
False	Loop back to the input Web Page (to surface an inline error) for recoverable failures; Failure Final for terminal failures
Named error edges (e.g. `accountlocked`, `emailunverified`)	A dedicated recovery path: unlock flow, verification email, etc.
Resend (on OTP Web Pages)	Wire back to the Send Email or Send SMS node so users can request a new code without restarting

warning

In production, always wire both True and False outputs on every node. Any unconnected edge means that user path ends silently with no redirect.

Anti-Patterns

AUTH INSTEAD OF IDENTITY LOOKUP BEFORE MFA

Auth verifies credentials and immediately issues an access token. MFA Configured State reads the session identity context that Identity Lookup populates: it does not work with the Auth-issued session in the way MFA nodes expect.

Login Web Page → Auth → MFA Configured State

Login Web Page → Identity Lookup → MFA Configured State

SEND EMAIL VS SEND SUSPENDED EMAIL FOR PASSWORD RESET

There are two valid password reset patterns: pick the right send node for the pattern you are building:

Reset via link in email (vtoken)

Web Page → Send Suspended Email → Reset Page

Send Suspended Email pauses the flow until the user clicks the link. The vtoken in the URL is validated before the True output fires.

Reset via OTP code entered by the user

Web Page → Send Email → OTP Entry Page → Verify OTP → Reset Page

Send Email sends the code and moves on immediately. The user types the code into the OTP entry screen.

Using Send Email expecting link-click validation: do not do this

Web Page → Send Email → Reset Page (expecting vtoken in URL)

Send Email has no vtoken mechanism. There is no token validation: anyone who receives the email URL can access the reset page without clicking.

MFA CONFIGURED STATE WITHOUT CONFIGURE MFA

MFA Configured State emits outputs for each registered method (SMS OTP, Email OTP, Backup Code). Its Failure output fires for users with nothing registered. Leaving that output unconnected means those users hit a dead end with no recovery path.

MFA Configured State Failure output → unconnected

MFA Configured State Failure → Configure MFA (set MFA Flow = Mandatory)

SKIPPING USER EXISTS BEFORE CREATE USER

Without User Exists, submitting the registration form for an existing email calls Create User and receives an error: which surfaces as an unhandled failure rather than a clean inline "already registered" message.

Web Page Output → Create User

Web Page Output → User Exists → (True: loop to form  |  False: Create User)

LEAVING AUTH'S NAMED ERROR EDGES UNCONNECTED

Auth exposes accountlocked, passwordexpired, emailunverified, and phoneunverified edges. Unconnected edges fall through to false (loop back to form), so a locked-out user sees a generic "wrong credentials" message with no recovery path.

accountlocked→ Route to Unlock Account node or a locked-account info page

passwordexpired→ Route to an Update Password screen

emailunverified→ Route to Send Email (verification template)

phoneunverified→ Route to Send SMS (verification template)