Staff roles

Give administrators a role (Administrator, Support, Read-only or your own) that limits what they may do, with per-role session rules.

Every administrator account is staff and holds a role. The level decides what staff see (every server and account); the role decides what they may do. Resellers and users have no staff role: their rules are their level, team roles and customer switches.

Built-in roles#

Role What it may do
Administrator Everything, including permissions added in later releases
Support Sees servers, customers, plans, nodes, networks, images, backups, tasks, sign-ins and the mail log. Starts, stops and reboots servers, opens consoles, and operates servers: rename, notes, ISO drives and boot order, hardware settings, root password reset, rescue. Deletes nothing, reads no secrets and changes no settings.
Read-only Every "see" permission; changes nothing

The built-in roles' permissions are fixed (their session rules can be changed). To make a variant, press Duplicate on a built-in role and edit the copy.

An administrator created with vmstack:create-admin, or one that existed before roles were installed, holds the Administrator role.

Making a role#

  1. Go to System › Staff roles › Add role.
  2. Give it a Name and an optional Description.
  3. Tick the permissions. There are 62, grouped by area: Servers, Customers, Staff, Nodes, Network, Images, Backups, Security, Logs, API, Settings and Billing. A permission that only reads is never one that reveals secrets (servers.secrets is separate).
  4. Under Sessions, optionally set Sign out after minutes without activity and One session at a time.
  5. Press Save changes.

Permissions you do not hold yourself are shown but cannot be ticked ("Your own role does not hold this").

Giving a role#

  1. Open the administrator under Customers › Users.
  2. With Level set to Administrator, choose the Role.
  3. Save.

Rules that stop privilege escalation:

  • Only someone with the Staff permission (staff.manage) whose own permissions cover a role can make, change, delete or give that role. Roles the editor may not give are disabled in the list.
  • The Administrator role is given, changed or taken away only by a full administrator, and a full administrator is managed only by another. A custom role with every permission ticked is still not the Administrator role: it does not receive permissions added later.
  • Nobody changes their own role. The last administrator with the Administrator role keeps it, cannot be deleted and (if it is the last one not suspended) cannot be suspended.
  • A role somebody holds cannot be deleted.

Where a role is enforced#

  • Pages: the sidebar shows only the pages the role opens; any other page answers 403.
  • Buttons and actions: a refused action shows "Your role (Support) does not allow this: …". Buttons are not all hidden; they refuse when pressed.
  • API keys: a staff member's key is held to both its scopes and its owner's role (403 forbidden). The key form offers only scopes the role allows. See API keys.
  • Sign-in links made through a staff member's billing key stop working when the maker's role no longer allows them.

Refusals are written to the audit log as staff.refused (at most once a minute for the same thing). Role changes are staff_role.*, and a change of an account's role is in user.updated.

Session rules#

A role can set:

  • Sign out after minutes without activity: the shorter of the role's and the panel's idle timeout applies. A role timeout also stops remember-me cookies from signing its holders in.
  • One session at a time: signing in ends the holder's other sessions.

Panel-wide timeouts and One session at a time for every administrator or every account are under System › Settings › Sign-in; see Sign-in security. Every open session of the panel is listed under Customers › Sessions, where an administrator with the users.sessions permission can sign one out.

Not available#

Roles are managed in the panel only (there are no API endpoints for them). There is no role-level address allowlist: each staff member sets allowed addresses on their own account under Settings › Sign-ins.