Add and manage panel users

A panel user is a person who signs in to the Hyperion panel. Owners manage them on the Users page, which is titled Admin users. The accounts live on the master, the server that runs the panel. See Concepts for the terms used in this manual.

Before you start

• Sign in as an Owner. Only Owners can open Users, under Administration in the sidebar. The page sends everyone else back to the dashboard.
• Pick the role first. The five built-in roles are listed in Built-in roles. To grant an exact set of permissions, create a custom role before you assign it.
• Decide how you will send the person their password. Hyperion does not email it.
• If every Owner is locked out of the panel, use Regain access to the panel instead.

Steps

Add a user

1. Open Users in the sidebar, then click + Add user. The form is already open when no users exist.
2. Fill in the fields.
   • Username: 3 to 32 characters. The form accepts letters, digits, ., _ and -.
   • Email: any address that contains @.
   • Initial password: at least 8 characters.
   • Role: Read-only, Customer, Operator, Administrator or Owner.
3. Click Create user. The page shows “User created” and the account appears in the list.

The Role list in this form offers built-in roles only. Assign a custom role after you create the user, as described next.

Change a role

1. In the Users list, click Manage on the user’s row.
2. Under Role, choose a role. Custom roles are listed under Custom, built-in roles under Built-in.
3. Click Save role. The page shows “Role updated”.

The change applies on the user’s next request. They are not signed out, and a session that is already open does not keep the old permissions. Choosing a built-in role removes any custom role from the user.

When you save a built-in role, Hyperion refuses to demote the last active Owner and shows “validation failed: refusing — this would leave the cluster with no active super_admin”. Create or unlock a second Owner first. The same guard covers locking and deleting. It does not cover assigning a custom role. See the caution in Create a custom role.

Lock or unlock sign-in

1. Click Manage on the user’s row.
2. Under Sign-in, optionally type a Reason (optional), then click Lock account.
3. To let the user in again, open Manage on the same row and click Unlock account.

A locked user is treated as signed out on their next request and cannot sign in. The sign-in page tells them “This account is locked. Ask an administrator to unlock it.” The reason you typed appears in the Sign-in section of their row.

Hyperion also locks an account on its own. Ten failed password attempts in a row lock it with the reason “too many failed login attempts”, and eight failed two-factor attempts lock it with “too many failed 2FA attempts”. Passwords and codes share one failure counter, and a successful sign-in resets it. You unlock these accounts the same way. The last active Owner cannot be locked.

Reset a password

1. Click Manage on the user’s row.
2. Under Password, type a New password (min. 8 chars).
3. Click Reset password and confirm Reset password in the dialog. The page shows “Password reset”.

Send the new password to the user yourself. Browser sessions that are already signed in stay signed in until they expire, which is eight hours after sign-in by default (session_ttl_secs in the [web] section of /etc/hyperion/web.toml).

Delete a user

Before you delete a user

Deleting a user removes the account and ends all of its sessions. Per-site access grants, backup codes for two-factor sign-in, notifications and any API keys the user created go with it, and scripts that use those keys stop working. Hostings the user could reach are not touched.

Hyperion keeps no way to restore a deleted account. Note the username, email and role from the user’s row before you continue. To bring the person back, use + Add user again and re-grant their site access. This cannot be undone.

The last active Owner cannot be deleted.

1. Click Manage on the user’s row.
2. Click Delete user at the bottom of the panel and confirm Delete user in the dialog. The page shows “User deleted”.

Check that it worked

• The Users list shows the account with the expected Role, a Status of active or locked, and the 2FA column set to enrolled or 2FA off.
• Last sign-in shows never until the person signs in for the first time.
• Every change is recorded. Open Audit log in the sidebar and choose the Sign-ins & users segment to see the web.user.* entries. See Review the audit log.

From a shell on the master you can list the same accounts:

sudo hctl user list

If it fails

• “validation failed: username and email are required”: one of the two fields was empty.
• “validation failed: email must contain ‘@’”: fix the address.
• “validation failed: password must be at least 8 characters”: use a longer password. This message appears for both Initial password and New password (min. 8 chars).
• “validation failed: refusing — this would leave the cluster with no active super_admin”: the change would remove the last active Owner. Add or unlock another Owner, then repeat the step.
• The role you want is missing from the Role list in Add user: custom roles are assigned from Manage after the user exists.
• A user you created cannot be picked on a site’s Access tab: see Give a user access to a site.