Building a Login Page
By the end you have your own passwordless sign-in at /login: the visitor enters an email address, receives a one-time code, types it in and lands signed in. No passwords to store, no reset flow to maintain.
1. The page starts with one form
A page you build at the URL login wins over the built-in one, so this page also becomes where visitors land when they open a page they may not see yet.
Add the page
Add a
web_page(new web page) block to a new blueprint. Set itseventtologinand its scope to*public: a login page is the one thing nobody is logged in for.Render it
Connect its flow to
web_render(web render), settitletoSign in, and write the template below on the block.Activate and open it
Activate the blueprint and open
/login. The form shows, and an invalid address is flagged in the browser without a request.
<main class="login">
<h1>Sign in</h1>
<div id="login-step">
<form data-action="request-code">
<label>Email <input name="email" type="email" autocomplete="email" required></label>
<div data-error-for="email"></div>
<div data-error-for="_form"></div>
<button type="submit" data-loading-text="Sending">Email me a code</button>
</form>
</div>
</main>2. A web action mails the code
Catch the form
Add
web_action(on web action) witheventset torequest-code. Itsformout-pin holds the posted fields; read the address withobject_field_getter_multiple(get fields).Normalize the address
Run it through
value_trim(trim) andvalue_to_lowercase(convert to lowercase), soAda@Example.comandada@example.comare the same person.Send the code
function_user_request_passwordless_code(request passwordless login code) takes the address asidentifierwithidentifier_typeset toemail, generates the code and mails it. The code is never exposed to the flow: there is nothing to log or leak.Answer both paths
Connect a
branch(branch) on the block'ssuccesspin. On true,web_update(web update) withtarget#login-stepswaps in the code form, rendered byweb_template(web template) with a custom pinemail. On false,web_errors(web form errors) with amessagesuch asWe could not send a code. Check the address and try again.
<form id="verify-code">
<p>We sent a code to {{email}}.</p>
<input type="hidden" name="identifier" value="{{email}}">
<label>Code <input name="code" autocomplete="one-time-code" required></label>
<div data-error-for="_form"></div>
<button type="submit">Sign in</button>
</form>error pin with function_console_log and show the visitor the generic text. 3. The built-in route turns the code into a session
No block checks a code. The cluster's own route does: POST /api/v1/auth/passwordless/verify takes the address and the code as JSON and answers with an access_token. A short script on the page calls it and stores the token in the same access_token cookie the built-in login page uses.
Add the script to the page template, below the main element. HTML that an action sends back never runs its scripts, so the script has to be on the page from the start and listen on the document.
<script nonce="{{nonce}}">
document.addEventListener('submit', async function (event) {
if (event.target.id !== 'verify-code') {
return;
}
event.preventDefault();
var fields = new FormData(event.target);
var reply = await fetch('/api/v1/auth/passwordless/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
identifier: fields.get('identifier'),
type: 'email',
code: fields.get('code')
})
});
var session = await reply.json();
if (!reply.ok) {
event.target.querySelector('[data-error-for="_form"]').textContent = 'That code did not work. Check it and try again.';
return;
}
document.cookie = 'access_token=' + session.access_token + '; Path=/; SameSite=Lax; Secure';
var next = new URLSearchParams(location.search).get('redirect') || '/';
location.assign(next.startsWith('/') && !next.startsWith('//') ? next : '/');
});
</script>Every page has a Content Security Policy, which is why the script carries nonce="{{nonce}}". The check on next keeps the redirect query from sending someone to another site.
How you know it worked: open a page scoped *loggedin in a private window. You are sent to /login?redirect=...; after the code you are back on that page, signed in.
verified: false, the 2fa methods and a token that still owes the challenge. Before you store it, finish the challenge at POST /api/v1/auth/<method>/verify (totp, otp, mobile and so on, named after the method in the list) with access_token in the JSON body. A password form needs no script at all
Prefer classic passwords? function_user_signin (sign in) checks them in the flow. Use a plain form with a hidden _action field, because only a full page answer can set a cookie: the update list a data-action form gets back carries no response headers.
<form method="post">
<input type="hidden" name="_action" value="sign-in">
<label>Email <input name="email" type="email" autocomplete="username" required></label>
<label>Password <input name="password" type="password" autocomplete="current-password" required></label>
{{if error}}<p role="alert">{{error}}</p>{{/if}}
<button type="submit">Sign in</button>
</form>Sign in
web_action(on web action) witheventsign-in. Wire the address touser_idand the password topasswordonfunction_user_signin.Build the cookie
On
success,value_concatenate(concatenate values) makes the header value:access_token=, then theaccesstokenpin, then; Path=/; HttpOnly; Secure; SameSite=Lax.Answer with a redirect
Build two
{key, value}objects withobject_new_fields(new object), oneSet-Cookieand oneLocationwith/account, and collect them witharray_of_objects(with objects). Wire that into theheaderspin of aweb_renderwithstatus303and a one-line template linking to/account.Answer a failure
On false, render the form again with
web_render,status401and a custom pinerrorholding one generic message. Log the block'serrorpin; it tells a wrong password from other failures.
Accounts with two-factor get need_2fa true plus the available 2fa_methods. Branch on it before the cookie step and finish with function_user_verify_2fa (verify 2fa), which takes the block's auth object, the method and the code.
The same step works as an API
For a mobile app or your own frontend, skip the page. The request block works behind an API trigger, as on the canvas, or call the cluster's routes directly: POST /api/v1/auth/passwordless/request with identifier and type, then POST /api/v1/auth/passwordless/verify with the code as well. Send the token on every later request; see Adding tokens to your requests.
A function trigger runs the endpoint: the request body is read with get body, get fields takes the email off it, and request passwordless login code mails the code. A branch on the success pin decides between a 200 reply and a 400, both sent with reply in JSON.
Notes from practice
- Throttle the action. It sends email, so it is a spam vector. Put
function_rate_limit(rate limit) at the start of the flow and branch onallowed. See Remote Access Control for the same protection on API blocks. - The block skips the short rate limit so a code can be sent right after account creation. One address still gets at most 5 codes per 2 hours and 10 per 24 hours; past that
errorisTOO_MANY_CODE_REQUESTS. - A code allows three attempts. After that it is gone and the verify route answers
TOO_MANY_ATTEMPTS, so offer a way to request a new one. - Session length is a cluster setting,
auth_access_token_expiry_days, not something the form decides. The script above sets a session cookie; addMax-Ageto keep it after the browser closes. - Password resets follow the same two-step shape with
function_user_request_password_reset_tokenandfunction_user_reset_password_with_token. - Answer every branch. An action with no updates leaves the page as it is, and an unanswered login attempt looks like a hung page, not an error.
- Locked out by a broken page? Append
?studio=requestto the URL to reach the default login again. See Overwrite Default Pages.
Next steps
Building User Authentication Roles, scopes and gated pages around this login flow. Single Sign-On Sign in with Apple, Google, TikTok, mssgs mail and passkeys. Forms and Validation What the browser checks by itself and what the action answers. Remote Access Control Scopes and rate limits in depth.Frequently asked
How do I build a passwordless login in RUAL?
Two steps: a web action takes the email address and calls function_user_request_passwordless_code, which mails a one-time code without ever exposing it to the flow. The page then posts the address and code to POST /api/v1/auth/passwordless/verify, the cluster's own route, which answers with an access token. No block checks a code: function_user_signin checks passwords only.
How do I set how long a RUAL login session lasts?
With the cluster setting auth_access_token_expiry_days, not per login. The expiry_date pin on the sign-in block is not read by the core.
Does RUAL login support two-factor authentication?
Yes. When an account has two-factor enabled, function_user_signin returns need_2fa true plus the available 2fa_methods, so the login endpoint can hand off to your second-factor step before issuing the token.
