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.

  1. Add the page

    Add a web_page (new web page) block to a new blueprint. Set its event to login and its scope to *public: a login page is the one thing nobody is logged in for.

  2. Render it

    Connect its flow to web_render (web render), set title to Sign in, and write the template below on the block.

  3. 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.

Page template
<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>
Keep login in a blueprint of its own An action without scopes of its own is allowed only for visitors every page of the blueprint allows. Next to an admin page, this public form would stop working.

2. A web action mails the code

  1. Catch the form

    Add web_action (on web action) with event set to request-code. Its form out-pin holds the posted fields; read the address with object_field_getter_multiple (get fields).

  2. Normalize the address

    Run it through value_trim (trim) and value_to_lowercase (convert to lowercase), so Ada@Example.com and ada@example.com are the same person.

  3. Send the code

    function_user_request_passwordless_code (request passwordless login code) takes the address as identifier with identifier_type set to email, generates the code and mails it. The code is never exposed to the flow: there is nothing to log or leak.

  4. Answer both paths

    Connect a branch (branch) on the block's success pin. On true, web_update (web update) with target #login-step swaps in the code form, rendered by web_template (web template) with a custom pin email. On false, web_errors (web form errors) with a message such as We could not send a code. Check the address and try again.

Template on web_template: the code form
<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>
Keep the failure message vague A precise error like "no account with this email" tells a caller exactly which addresses have accounts. Log the block's 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.

Add to the page template
<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.

Accounts with two-factor are not done yet With two-factor on, the reply carries 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.

A plain sign-in form
<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>
  1. Sign in

    web_action (on web action) with event sign-in. Wire the address to user_id and the password to password on function_user_signin.

  2. Build the cookie

    On success, value_concatenate (concatenate values) makes the header value: access_token=, then the accesstoken pin, then ; Path=/; HttpOnly; Secure; SameSite=Lax.

  3. Answer with a redirect

    Build two {key, value} objects with object_new_fields (new object), one Set-Cookie and one Location with /account, and collect them with array_of_objects (with objects). Wire that into the headers pin of a web_render with status 303 and a one-line template linking to /account.

  4. Answer a failure

    On false, render the form again with web_render, status 401 and a custom pin error holding one generic message. Log the block's error pin; 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.

Studio canvas example for the request passwordless login code block: the request-code half of passwordless login.

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 on allowed. 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 error is TOO_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; add Max-Age to keep it after the browser closes.
  • Password resets follow the same two-step shape with function_user_request_password_reset_token and function_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=request to 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.