Set up cPanel Team Manager for delegated account access

Team Manager is the per-account delegation system inside cPanel. It replaces the old Sub-Accounts feature and the unofficial workflow of just sharing the cPanel password with a developer or agency. A team user logs in with their own email and password, sees only the parts of cPanel their role grants, and shows up under their own name in the activity log.

This guide covers the WHM-side prerequisites, adding a team user end-to-end, what each of the four roles actually unlocks, and the operational settings — expiry, 2FA, password strength — that decide whether the feature is worth turning on for paying customers.

What Team Manager replaced

Sub-Accounts let a cPanel user create a single combined login that shared a password across Email, FTP, and Web Disk. It did not delegate cPanel UI access at all. Team Manager is structurally different — each team user is a real cPanel login, with its own 2FA, its own API tokens, and a role that scopes what they can see and do.

If you are migrating away from cPanel SubAccounts, the WHM Transfer Tool does not carry team users — they are recreated on the destination by the account holder after the transfer completes.

Prerequisites

Team Manager has shipped on every cPanel release since v102, but the role catalogue expanded substantially in v110 and the Web role only became useful in v112. Run a recent release before exposing it to customers:

/usr/local/cpanel/cpanel -V

Confirm v110.0 or newer. If you are on an LTS branch, you want the latest LTS point release.

Then check that team users are actually enabled at the server level. WHM → Server Configuration → Tweak Settings → Team Manager must be On. It is on by default for new installs but explicitly off on some control-panel images from cloud providers — worth verifying on a fresh cPanel VPS install.

The per-package limit is set under WHM → Packages → Edit a Package → Maximum Number of Team Users with Roles. Default is 7. Setting this to 0 disables Team Manager for every account on that package without touching the global toggle.

Add a team user

Inside cPanel, the account holder opens Preferences → Manage Team, then Create Team User. Three fields matter:

• Username — local part only. The team user logs in as developer@example.com where example.com is the primary domain on the account. They cannot pick a different domain.
• Contact email — must not be on the same cPanel account. Password resets and notifications go here.
• Password — generate one. The team user can change it on first login.

Tick one or more roles before saving. Roles are additive and can be edited later without recreating the user.

The four roles

Each role gates a specific slice of the cPanel UI and the corresponding API. A user with no roles still exists but cannot log in usefully — they see an almost empty home screen.

The Administrator role is the dangerous one — it grants API token creation, which means that user can mint long-lived credentials with their own access scope. Treat Administrator team users as equivalent to handing over the primary password and only use it when you trust the person with the whole account.

Password expiry and 2FA

By default a team user's password never expires and 2FA is optional. Both should change before you rely on team users for a real workflow:

• Expiration — on the team user's row, click Edit, then set Expiration to a fixed date. Useful for contractor engagements. The user can still log in until the date, then is locked out automatically.
• 2FA — if WHM → Two-Factor Authentication is set to Required for all users, team users inherit that requirement. Otherwise it is per-user opt-in via the team member's own Security tab. Server-wide enforcement is the only sane setting for a shared hosting product.

There is no per-role 2FA enforcement. Either everyone must use it or nobody must — a gap that has been on the cPanel roadmap for two releases now.

Auditing what team users did

Team Manager writes to the standard cPanel access log, but under the team user's identity. The fastest way to review activity is Manage Team → View Activity in cPanel, which surfaces logins, password changes, and role edits. For richer auditing — specifically, which files a Web-role team user touched — you need the underlying session log on the server:

grep "team_user=developer" /usr/local/cpanel/logs/session_log | tail -50

If you need to ship team-user activity to a SIEM, the cPanel JSON access log under /usr/local/cpanel/logs/access_log includes the team_user field on every authenticated request. Forward that, not just /var/log/secure, or you will miss everything that happened inside the panel.

Automating with the API

Team users can be managed via WHM API 1 and cPanel UAPI. The two endpoints worth knowing:

# create a team user (WHM, runs as root)
whmapi1 create_team_user user=customer \
  team_user=developer \
  password=GENERATED_HERE \
  contact_email=dev@agency.example \
  roles=web,database

# list team users on an account (cPanel UAPI, runs as the account holder)
uapi --user=customer Team list_team

Useful for provisioning developer access during onboarding flows in Blesta or any other billing platform that already calls WHM on signup. The token used for whmapi1 needs the account-management ACL.

Common gotchas

Team users cannot see the account's API tokens. Even Administrator team users only see tokens they themselves created. The primary user's tokens are invisible to them — by design, but it surprises agencies who expect a single token list.

Web role does not include MultiPHP INI Editor on every version. Until cPanel 116, that page was Administrator-only. If your developer needs to flip a php.ini value, either upgrade or temporarily promote them.

Resellers see team users in their account list. They count against the reseller's account limit only as the parent account, not per team user — but they do appear in list output, which trips up scripts that count rows. Filter on is_team_user=0 if you want primary accounts only.

Removing a role does not revoke active sessions. A demoted user keeps their session until it expires (24h default) or until you terminate it under WHM → Manage cPanel Sessions. For contractor offboarding, delete the team user rather than removing roles — deletion ends the session immediately.

FAQ

Next steps

• WHM reseller accounts and ACLs — for delegating across multiple accounts rather than within one
• cPanel license tiers explained — what team users do and don't count toward
• Activate or transfer a cPanel license — buy or move the underlying license before you start provisioning team access