Users#

Admin → Users lists the accounts that sign in to the web interface. It is where an admin adds them, changes a role, resets a password, clears a user's two-factor authentication, links a user to an identity provider, or deletes one. The page's subtitle: "Accounts that sign in to this web interface, and their roles."

None of this is router configuration. These accounts are kept by the agent, not in the router's configuration, so nothing here goes to the pending changes, and restoring an earlier configuration does not undo it. Every change takes effect when you save it, and every one is written to the audit log.

The page is admin-only. Other roles do not see it in the navigation, and the agent refuses its requests from them.

The four roles#

Across the top, one card per role, with how many accounts hold it and the sentence the page uses for it:

Role	What the page says
Viewer	Sees everything. Changes nothing.
Approver	Applies, keeps and reverts changes others have prepared, and restores earlier configurations. Cannot prepare changes, and does not see the secrets in them.
Operator	Prepares and applies changes, and restores earlier configurations.
Admin	Everything an operator can do, and manages users, API tokens and settings.

Roles has everything each role can do, as the agent enforces it.

The accounts table#

The Accounts panel has one row per account. Click a row to change the account.

Column	What it shows
User	The account name. Your own account carries a You badge.
Role	Viewer, Approver, Operator or Admin.
Two-factor	On, or Off.
Password	Set; Must change when the account has to choose a new password at its next sign-in; None, single sign-on only when the account has no password at all.
Single sign-on	The start of the identity provider's ID for the account, with the whole ID when you hover over it — or Not linked.
Created	How long ago.
Last sign-in	How long ago, or Never.

The Password and Single sign-on columns together answer one question: which accounts can sign in, and how.

Adding a user#

Add user opens a panel with three fields — Username, Initial password and Role — and the chosen role's sentence under them. The panel's subtitle: "They change the password at their first sign-in."

A username is letters, digits, dots, hyphens and underscores, up to 64 characters. Anything else is marked under the field: "Enter a name of letters, digits, dots, hyphens and underscores." Add user stays disabled until the name is valid and a password is filled in.

The agent then checks, in this order:

A name is required, in that shape.
Two names are reserved: admin-token, and anything beginning token:. Those are the names the break-glass token and API tokens act under, and an account with one of them could not be told apart from them in the audit log.
The role must be one of the four.
The password must not be empty, and must be at most 1,024 characters. There is no minimum length and no complexity rule — Account says what protects the sign-in instead.
The name must be free.

The new account has to choose a new password at its first sign-in, and the audit log records who added it, from which address, its name and its role.

Changing a user#

Clicking a row opens a panel titled with the account name, with its role and when it was added underneath. Save changes is disabled until something changes, and sends only what did. The panel's sections, in order:

Account#

Facts, not settings: Two-factor (On or Off), Password (Set, Must change at next sign-in, or None) and Last sign-in.

Role#

A choice of the four roles, with the chosen role's sentence under it. When the change gives or takes away the ability to prepare or apply changes, a note in amber says what, before you save:

The change	The note, for a user called alice
To viewer, from any other role	"alice will no longer be able to apply changes or restore earlier configurations."
From operator or admin to approver	"alice will still apply changes others prepare, and will no longer be able to prepare their own."
From viewer to operator or admin	"alice will be able to prepare and apply changes and restore earlier configurations."
From viewer to approver	"alice will be able to apply changes others prepare and restore earlier configurations, but not prepare changes."
From approver to operator or admin	"alice will be able to prepare changes as well as apply them."

Moving between operator and admin shows no note: it changes who manages users and settings, not who changes the router.

The agent refuses to demote the last admin: "this is the only admin — promote another before changing this one". It counts the admins and makes the change under one lock, so two demotions at the same moment cannot leave the router with no admin.

Password#

New password, with the hint "Leave empty to keep the current password. They change it at their next sign-in." A new password:

makes the account choose another at its next sign-in;
removes the first-start password file, when the account is the one the agent created when it first started;
signs the account out everywhere. A role change, a new password and a change of identity provider ID each end every session the account holds, and the message after saving says so.

On your own row the section has no field. It says "Change your own password on the Account page." — Account changes it and keeps the session you are using.

Single sign-on#

One field, Identity provider ID, with the hint "The provider's ID for this person, not their email. Empty unlinks the account." It is the provider's own identifier for the person (the sub claim). The field is sent only when you change it, so saving a role change cannot unlink somebody by accident.

The agent refuses an ID another account is already linked to, and the refusal names that account. When the account has no password of its own, the section warns: "This account has no password. Set one before unlinking single sign-on."

Linking is how an identity reaches an existing account. At sign-in, an identity whose username matches a local account that is not linked to it is refused rather than handed that account — Single sign-on.

Second factor#

The panel's Two-factor authentication section, and the answer to a lost phone. It reads one of three ways:

The user has not set up two-factor authentication. It says so — "alice has not set up two-factor authentication." — and adds "They are asked to at their next sign-in." when two-factor authentication is required.
It is your own row. "Turn off your own two-factor authentication on the Account page." Clearing your own here would be a way round the requirement, so the page does not offer it and the agent refuses it. If you have lost your authenticator, ask another admin.
Another user, with two-factor authentication on. "Clearing removes alice's authenticator and recovery codes and signs out their sessions.", and Clear two-factor authentication, which asks "Clear alice's two-factor authentication?" before it acts.

Clearing does exactly four things: it deletes the authenticator secret, and any secret still being set up; it deletes every recovery code the account holds; it signs out the account's sessions; and it writes a totp-admin-clear entry to the audit log naming both of you — you as the one who acted, them as the account it was done to. They then sign in with their password alone.

It does not turn off Require two-factor authentication on Agent settings. With that on, the account is asked to set up two-factor authentication again at its next sign-in and can reach nothing else until it has. That is the requirement working: an admin restoring one person's access cannot quietly remove everybody's requirement to do it. The message after clearing says which applies — "They set it up again at their next sign-in.", or how many sessions were signed out.

The agent also refuses a clear when there is nothing to clear, so the audit log never records one that changed nothing.

Deleting a user#

Delete user, at the foot of the panel, asks "Delete alice?" before it acts. It is not offered on your own row, and the agent refuses it anyway: you cannot delete the account you are signed in as, and you cannot delete the last admin. Deleting removes the account's sessions with it, and is recorded in the audit log.

Deleting a user does not revoke API tokens they issued. A token is a separate credential with its own role — API tokens.

What this page is not#

Not the router's accounts. The accounts for the router's console and SSH are router configuration, under System → Settings tab → Router accounts, and a change to them is applied like any other — System — settings. The users here exist only in the web interface.
Not per-object permissions. There are four roles, enforced on every request. A user cannot be given the firewall and not NAT.
Not a directory integration. Mapping an identity provider's groups to roles exists for single sign-on and is set by the agent's own options, not here — Single sign-on.

For automation#

GET /api/admin/users lists the accounts and POST /api/admin/users adds one. PATCH /api/admin/users/{name} changes the role, the password or the identity provider ID, and changes only the fields the body carries. DELETE /api/admin/users/{name} deletes an account, and POST /api/admin/users/{name}/totp/clear clears its two-factor authentication. All of them are admin-only. A refusal answers 409 — the last admin, your own account, an ID already linked elsewhere, a name already taken, nothing to clear — or 400 for a name, role or password the agent does not accept.