WebRobot
App Builder · pages

Documentation · App Builder

Sign-in and roles

The sign-in method

spec.auth.method takes one of two values:

ValueWhat happens
magic_link (default)Users sign in with their email address: no password. The header shows a Sign in button.
noneThe 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 }

The sign-in page is /login. The flow:

  1. The user types their email address and presses Send me the link.
  2. 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.
  3. 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.
  4. The app sets the session and opens the page the user came from (the next page), or the home page.

Rules of the link and the code:

LinkCode
Valid for15 minutes15 minutes (the same sign-in as the link)
Useonceonce
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, and Secure on 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:

SettingEffect
auth.anonymous.views: [<view key>, …]Visitors may open these views.
auth.public: trueVisitors 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, or public: true), and only into a collection ownedBy: 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: app or shared. 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.

assignedByHow a user gets the role
admin_emailsThe user's address is in the app's list of admin addresses. These are the app's admins.
signupEvery user who signs in and has no other role.
derivedA record of a collection names the user's email (see below).
admin, inviteGranted 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:

  1. admin_emails, if the address is on the admin list;
  2. a role granted on the user's account (admin / invite);
  3. the signup role. If the manifest has no signup role, the user's role is user.

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 }
  • from is collection:<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 signup role gets a derived role. They keep the signup role 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 viewSigned-in users who can open it
not set, or emptyeveryone 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 roles is hidden from other roles. In the run form, a hidden field gets its default.
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: app or shared: everyone reads them;
  • ownedBy: org: admins only;
  • access rules 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.