Documentation · App Builder
Sign-in and roles
The sign-in method
spec.auth.method takes one of two values:
| Value | What happens |
|---|---|
magic_link (default) | Users sign in with their email address: no password. The header shows a Sign in button. |
none | The header shows no Sign in button, and visitors can open every view. What needs a user still sends the visitor to sign in: the history and account views, forms not open to visitors, starting a run, chatting, uploading a file, booking. |
auth:
method: magic_link
anonymous: { views: [home, pricing] }
roles:
- { key: admin, assignedBy: admin_emails }
- { key: user, assignedBy: signup }
Signing in with an email link or code
The sign-in page is /login. The flow:
- The user types their email address and presses Send me the link.
- The app sends one email with two ways to sign in: a link and a 6-digit code. The email comes from WebRobot on behalf of the app and names the app. The subject is "Sign-in link for «App name» (via WebRobot)". The email is in Italian when the page is in Italian, otherwise in English.
- The user either opens the link, or types the code on the page that is still open. The code is there for the phone app: on a phone the link opens the browser, not the app.
- The app sets the session and opens the page the user came from (the
nextpage), or the home page.
Rules of the link and the code:
| Link | Code | |
|---|---|---|
| Valid for | 15 minutes | 15 minutes (the same sign-in as the link) |
| Use | once | once |
| Wrong attempts | — | after 5 wrong codes the sign-in is cancelled (the link stops working too): ask for a new one |
When several sign-ins are pending for the same address, the code is checked against the newest one.
The errors a user can see: link already used, link expired, invalid link, wrong code,
code expired: ask for a new one, too many attempts: ask for a new code, invalid email.
Limits on sign-in
To protect inboxes and the app, the runtime limits sign-in requests:
- 10 requests per hour from one network address, per app;
- 3 emails per hour to one address, per app. Further requests get the same "sent" answer, but no email leaves;
- a cap per app per hour on the number of sign-in emails;
- 20 code checks per hour from one network address, per app.
A blocked request gets too many requests, try again later.
First sign-in creates the account
There is no separate sign-up. The first time an address signs in, the app creates its user. If
billing.signupCredits is set, the new user gets those credits at that moment. See Billing.
Sessions
After sign-in the browser keeps one session cookie for the app:
- it lasts 30 days;
- it is
HttpOnly(scripts on the page cannot read it),SameSite=Lax, andSecureon https; - it is bound to one app: a session of one app never opens another app, even on the same parent domain;
- the user's role is worked out again on every request, so a change of role takes effect at once, without signing in again.
The draft preview opened from App Studio uses its own sessions, separate from the published app's users. The preview opens only for the app's admins, or from App Studio. See App Studio.
Signing out
Sign out in the header clears the session cookie in that browser and goes back to the home page. In the phone app it also stops push notifications for that user on that device.
Visitors who are not signed in
By default every view needs a signed-in user. A visitor who opens one is sent to /login and comes back after
signing in.
Two settings open views to visitors:
| Setting | Effect |
|---|---|
auth.anonymous.views: [<view key>, …] | Visitors may open these views. |
auth.public: true | Visitors may open every view. Meant for apps whose pages are read without login. |
With public: true (and with method: none) the roles of a view do not stop visitors from opening it. What the
view shows still follows the data rules: a visitor never reads user records or the owner's back office.
What a visitor still cannot do:
- Forms. A visitor can send a form only if the form's view is open to visitors (listed in
anonymous.views, orpublic: true), and only into a collectionownedBy: org(the owner's inbox). At most 5 submissions per hour from one network address per form. Visitors cannot attach files. See Data. - Runs, chat, bookings, files. These always need a signed-in user.
- Data. Visitors read only collections
ownedBy: apporshared. See Data. - Pages that belong to a user (history, account, a run's report) are left out of a page shown to a visitor.
auth.anonymous.agents lists agents visitors may use without signing in. Validation makes sure such agents have no
tool that reaches the owner's private data or writes shared data. The web chat does not use this list today: chatting
always needs a signed-in user.
Roles
spec.auth.roles lists the roles of the app. Each role has a key, an optional label (translatable) and
assignedBy, which says how a user gets it.
assignedBy | How a user gets the role |
|---|---|
admin_emails | The user's address is in the app's list of admin addresses. These are the app's admins. |
signup | Every user who signs in and has no other role. |
derived | A record of a collection names the user's email (see below). |
admin, invite | Granted on the user's account. There is no page in the runtime to grant them yet. |
A user's role is resolved in this order:
admin_emails, if the address is on the admin list;- a role granted on the user's account (
admin/invite); - the
signuprole. If the manifest has nosignuprole, the user's role isuser.
Then, if the role from step 3 applies, the runtime checks the derived roles.
Derived roles
A derived role follows your data. The user holds it while a record names their email:
auth:
roles:
- { key: admin, assignedBy: admin_emails }
- { key: client, assignedBy: signup }
- { key: consultant, assignedBy: derived, from: collection:consultants.email }
fromiscollection:<name>.<emailField>, or a list of them: any match gives the role.- The field may hold one address or a list of addresses. Addresses are compared ignoring case and surrounding spaces.
- The roles are checked in the order of the manifest; the first match wins.
- Only a user who would otherwise have the
signuprole gets a derived role. They keep thesignuprole beside it: a view, a form field or an access rule for either role works for them. - The role is checked on every request. Delete or change the record, and the role goes away.
The app's admins
The admins of an app are the users whose role has assignedBy: admin_emails and whose address is on the app's
list of admin addresses. The list is not part of the manifest: the platform supplies it to the runtime with the
app. If no role has assignedBy: admin_emails, the app has no admins.
What admins can do that other users cannot:
- read and change every record of every collection, whatever its owner (see Data);
- open every run's report and every uploaded file;
- the Data page (
/admin/data), to manage catalogues and back-office data by hand or from a CSV; - the Notifications page (
/admin/push) when the app sends push notifications; - a view of type
admin: users, balances, adding credits, the latest runs (see Views); - decide every approval, except those the requesting user decides (
decidedBy: requester); - run agents without paying, and without the limits in
spec.limits; - use plan-gated fields and options, and see data blocks reserved to a plan;
- open the draft preview of the app.
Admins do not skip the roles of a view. A view with roles: [user] is hidden from an admin whose role is
admin. Add the admin role to the views they need: roles: [user, admin]. The design check warns when the admin
role is in no menu view.
What each role sees
A view's roles decides who opens it:
roles on the view | Signed-in users who can open it |
|---|---|
| not set, or empty | everyone signed in |
[a, b] | users who hold role a or b (their role, or the signup role kept beside a derived role) |
A user who cannot open a view gets "not found". A visitor is sent to sign in.
The same check decides:
- which views appear in the menu (see Views);
- which views appear inside a page, a dashboard or tabs;
- which form fields are shown: a field with
rolesis hidden from other roles. In the run form, a hidden field gets itsdefault.
views:
- { key: requests, type: table, source: collection:requests, roles: [consultant, admin] }
- { key: new_request, type: form, collection: requests, roles: [client] }
What ownership changes
Roles decide which pages a user opens. Which records the user sees on those pages comes from the collection's owner and its access rules:
ownedBy: user: each user sees their own records;ownedBy: apporshared: everyone reads them;ownedBy: org: admins only;accessrules give a role more records, e.g. the requests assigned to a consultant.
The full rules are in Data.
Language
When metadata.langs has more than one language, the header shows one button per language (EN, IT…). Pressing one
remembers the choice in the browser for a year and reloads the same page. Without a choice, the app uses the first
language of the browser's preferences when the app has it, else metadata.defaultLang. See
The manifest.