Building User Authentication

Sign-in, sessions, scopes, and gated pages for your app. The complete authentication system on a RUAL cluster.

Every RUAL cluster already has accounts, sign-in, sessions, and token management built in. Your job is to wire your app's pages and APIs to that system: not to build one. This tutorial assembles the full picture.

What the Cluster Handles for You

User accounts with passwords (and optional 2FA), created by an administrator. See User Access Management.
The default login, password reset, and security pages, ready at your cluster URL. See Overwrite Default Pages.
Sessions and access_tokens (14-day validity, auto-extending), accepted in five locations. See API Guide, Authentication.

Deciding Who Can See What

Every page and API gets its audience from a scope:

Scope	Who passes	Use for
`*public`	Anyone, no token	Landing pages, status endpoints, public content
`*loggedin`	Any valid `access_token`	Member areas, app pages, private APIs
Custom scope (e.g. `billing_read`)	Users you granted that scope	Role-gated sections (admin, finance, support)

Set scopes per page block or API block via its lock icon: full mechanics in Remote Access Control. Grant custom scopes to users on their user detail page (custom_scopes) or bundle them in user groups. See User Roles Explained.

The Sign-In Flow

A visitor hits a page scoped *loggedin without a token → the cluster serves the login page.
They sign in (password, plus 2FA code when enabled) → the cluster issues an access_token and redirects back.
The token travels as a cookie in the browser, or as a header/query param from your own frontend.
Sign-out invalidates the token immediately; users manage their sessions on the default security page.

Building your own frontend? Call the sign-in API directly (POST /api/v1/auth/signin) and store the token. See the API workflows. For 2FA-enforced clusters, pass the current code from the user's authenticator.

Knowing Who's Calling

Inside any authenticated flow, the user_current block gives you the calling user's document: guid, name, scopes. Typical uses:

Filter data to the caller (owner_guid = user.guid in your queries. The denormalized owner pattern from Storages).
Branch on scope: allow admins to a management view, others to their own data.
Audit: write the actor onto every document you create.

Gating Pages and Sections

Public marketing pages: scope *public.
The app shell and member pages: scope *loggedin: unauthenticated visitors bounce to login automatically.
Admin-only sections: a custom scope granted to admins only.
Locked yourself out with a custom login page? Recover with ?studio=request. See Overwrite Default Pages.

Hardening Checklist

Enable 2FA for everyone who can reach Studio or admin scopes.
Keep *public for content that truly is public. Check every page and API block once before launch.
Prefer custom scopes over checking usernames in flows.
Review the failed-login blocking and rate limits in Remote Access Control.
Audit access regularly on the User Activity page. See Auditing User Access.

Next Steps

Getting Access Accounts, first login, cluster URLs, and API tokens. Remote Access Control Scopes, rate limits, and throttling in depth. User Roles Explained Permissions, scopes, and user groups by role.

Frequently asked

Do I need to build a login system in RUAL?

No. Every cluster already has accounts, sign-in, sessions and token management built in, including default login, password reset and security pages. Your job is to wire your app's pages and APIs to that system through scopes, not to build one.

How do I restrict a RUAL page to logged-in users?

Set the *loggedin scope on the page block through its lock icon. Unauthenticated visitors are then served the login page automatically, and after sign-in the cluster issues an access token and redirects them back.

How do I know which user is calling my RUAL flow?

The user_current block gives you the calling user's document with its guid, name and scopes. Use it to filter data to the caller in your queries, to branch on scope, or to write the actor onto every document you create.

How long does a RUAL access token stay valid?

14 days, extended automatically while actively used. Sign-out invalidates the token immediately, and users manage their sessions on the default security page.