---
title: "Building User Authentication · RUAL Documentation"
description: "Login, tokens, 2FA and the scope checks around them."
canonical: https://docs.rual.nl/tutorials/user-authentication
language: en
---

# 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](https://docs.rual.nl/cluster/user-access-management).

- The default **login**, **password reset**, and **security** pages, ready at your cluster URL. See [Overwrite Default Pages](https://docs.rual.nl/interfaces/overwrite-default-pages).

- Sessions and `access_token`s (14-day validity, auto-extending), accepted in five locations. See [API Guide, Authentication](https://docs.rual.nl/cluster/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](https://docs.rual.nl/blueprints/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](https://docs.rual.nl/cluster/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](https://docs.rual.nl/cluster/api-guide#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](https://docs.rual.nl/blueprints/storage)).

- 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](https://docs.rual.nl/interfaces/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](https://docs.rual.nl/blueprints/remote-access-control).

- Audit access regularly on the User Activity page. See [Auditing User Access](https://docs.rual.nl/cluster/user-access-management#auditing).

### Next Steps