users
Accounts, roles and Samba credentials: the admin, viewer and share-only roles, per-account passwords (which write the UI credential and the Samba passdb entry together), user groups and session list/revoke. Account recovery over the Unix socket and personal API tokens are also under this tag.
List accounts
Every account, sorted by username.
Create an account
Defaults to the share-only role when omitted: a new account has no UI login until an admin promotes it. No password is set by this call — setUserPassword provisions the UI credential and the Samba account together, in a separate action. Never creates an admin account (users_one_admin_idx allows exactly one, created only by createFirstAdmin).
Change an account's role
Viewer or share-only only — the sole admin account is never reachable through this operation.
Delete an account
Removes the account, its sessions, its group memberships and its per-share permissions. Refuses the sole admin account.
Set an account's password
Writes the UI credential hash and the Samba passdb entry together: if the Samba write fails, the UI credential is rolled back to its previous value, and nothing is left updated on only one side. This is the ordinary admin-driven password action on `/users` — distinct from resetUserPassword, which is root-only recovery for a locked-out account over the Unix socket and never touches the Samba passdb.
Get one account's per-share access
Every share this account has an explicit access level for. A share with no row here is not represented — none of the three levels is assumed.
Replace one account's per-share access
A full replace: the account's access is set to exactly the shares and levels listed, and every share this account previously had an explicit level for but that is missing from the request loses its row entirely (access is editable from either the share or the user; this is the user-side editor).
List user groups
Every user group, sorted by name.
Create a user group
A named collection of accounts, purely for bulk share-permission assignment — distinct from the fixed `users` system group (GID 100) that every share's files belong to.
Delete a user group
Also removes its memberships and its per-share permissions.
Replace a user group's membership
A full replace of the group's member list.
List active sessions
Every session across every account, with revoke.
Revoke a session
Ends this session immediately, server-side — the same effect as that session's own logout, forced by an admin.
Create a personal API token
A personal API token, scoped to admin or viewer, for scripting and the remote CLI over TCP. The raw token is returned only here, once — only its SHA-256 is ever stored afterward, mirroring how a session cookie is handled. Refused for a share-only account (share-only has no API access at all), and refused when role exceeds the account's own role: a token can narrow an account's access (an admin can hand out a viewer-scoped token to reduce a script's own blast radius), never widen it.
List personal API tokens
Every account's tokens, most recently created first.
Revoke a personal API token
Ends this token immediately — the request it would have authenticated next is refused the moment this returns, since every request looks the token up fresh (no caching).
Reset a user's password
Root-only over the Unix socket. Checked against the peer's uid 0 specifically — the `hoserva` group and TCP are refused. Audit-logged and announced through every notification channel.
Disable a user's TOTP
Root-only over the Unix socket. Checked against the peer's uid 0 specifically. Audit-logged and announced through every notification channel.
Clear login lockout
Clears the account's login rate-limiter lockout. Root-only over the Unix socket, checked against the peer's uid 0 specifically. Audit-logged like the other recovery commands.