user management

Manage registered user accounts, global roles, and site assignments. This is an internal owlette page; customer accounts manage per-site access from members instead.

Location: admin panel -> user management (/admin/users)

Internal page

/admin/users is operated by owlette. It acts on accounts platform-wide, so it is not part of the site-scoped admin panel. To manage who can reach one of your sites, use member management (/admin/members).

account creation

The user-management page does not invite users or create accounts directly. Users register through the normal sign-up flow, using email/password or Google sign-in, and the first sign-in creates a users/{uid} document with:

role: "member"
sites: []
MFA setup flags and default user preferences

After the account exists, this page can assign sites or change the account's role. There is no shipped SAML/OIDC SSO mapping or invite-code workflow on this page.

the role model

role	platform access	site access
member	none	read-only access to the sites they belong to, plus self-service preferences and self-delete
admin (site admin)	the site-scoped admin panel pages — members, agent tokens, schedules, alerts, webhooks	write access on the sites they belong to, including machine commands/configuration, deployments, roosts, talons, site webhooks, logs, and site membership
internal	every admin panel page, including this one	every site, regardless of assignment

The third tier is reserved for owlette operators; it is never granted to a customer account, and the dashboard never names it in customer-facing copy — an internal operator appears as an admin on a site's member list.

Role is an account-level property: changing it here applies to every site the account belongs to. That is why site admins cannot change roles from /admin/members — granting admin there would grant it on every other site that account belongs to as well.

user list

The page listens to the users collection in real time and shows registered user documents ordered by newest registration first.

column	description
user	Display name when present, email address, and a `You` badge for the signed-in operator
role	Role badge for the account
sites	For admins, the assigned site IDs are shown as pills. For members, the page shows an assigned-site count. Internal accounts show `all sites`.
joined	Registration date from `createdAt`
actions	Row menu for `manage sites`, `change role...`, and `delete user`

The header cards show total users, members, site admins, and internal accounts.

changing a user's role

Open the row menu.
Select change role....
Pick the new role.
Select save role.

Promoting calls POST /api/users/{uid}/promote with the selected role. Demoting to member calls POST /api/users/{uid}/demote. Both routes require the USER_ROLE_MANAGE capability, which no customer role holds.

The dialog disables save role when the selected role matches the current role. The signed-in operator cannot open the role-change dialog on their own row, and the server also rejects any role change that would remove the last active internal account.

Role changes update the user document immediately. The affected user may need to sign out and back in, or wait for session refresh, before their navigation and permissions reflect the new role everywhere.

site assignment

Use manage sites to add or remove site IDs from a user's sites array. The dialog lists assigned sites, available sites, and invalid site references that no longer resolve to visible site documents.

action	behavior
assign	Adds the site through `POST /api/users/{uid}/assign-sites`. The server validates that each site exists and uses an idempotent array update.
remove	Removes the site through `POST /api/users/{uid}/remove-sites`. The membership change is immediate, and the server best-effort cancels pending commands that user issued on removed sites.

These endpoints require SITE_MEMBER_MANAGE. Site admins hold the same capability for their own sites and use it from /admin/members, which never lists accounts outside the selected site.

For member users, site assignment controls which sites they can read. For admin users, assignment controls where their site-scoped write capabilities apply. Internal accounts reach every site without assignment.

deleting a user

The row menu includes delete user for other users. The action is disabled on the signed-in operator's own row, and clicking it opens a confirmation dialog.

Deletion calls DELETE /api/users/{uid} and is a soft-delete cascade, not a simple row removal:

sets users/{uid}.deletedAt
preserves the user document for audit and historical references
revokes the user's API keys in both the user subcollection and top-level lookup docs
best-effort cancels pending commands issued by that user on their assigned or owned sites
refuses to delete a user who owns sites unless the API request supplies a valid successorUid for ownership transfer

The current dialog does not collect a successor user. If a delete request fails because the target owns sites, transfer site ownership through an API workflow that can pass successorUid, then retry deletion.

The server preserves deleted user documents with deletedAt for audit; default API list calls exclude those records. Reissuing the delete request for an already-deleted user is idempotent and returns the original deletion timestamp.

permission checklist

Use member for users who only need read access to the sites they belong to, plus self-service account controls.
Use admin for operators who need write access on specific sites and the site-scoped admin panel pages.
Keep at least two active internal accounts so one can recover the other.
Review user deletion carefully: it revokes API keys and may cancel queued work issued by the deleted account.