EN Token and Permissions

Token and permissions

The panel talks to Proxmox through an API token. This is where newcomers get stuck most often, and usually not because the panel is broken: a token newly created by Proxmox has no permissions at all.

中文版：PVE Token 与权限

1. Create a dedicated user and token

# do not use root@pam directly
pveum user add panel@pve --comment "ProxCenter panel"

# --privsep 0 means the token inherits every permission of the user
pveum user token add panel@pve panel --privsep 0

The output contains full-tokenid (like panel@pve!panel) and the token secret.

2. Grant permissions

pveum acl modify / --user panel@pve --roles PVEVMAdmin,PVEDatastoreUser,PVESDNUser,PVEAuditor,PVEVMUser

Or split them for least privilege:

Capability	Role
Read-only browsing, monitoring	PVEAuditor
Power operations, console	PVEVMUser
Create / delete / reconfigure / snapshot	PVEVMAdmin
Backups, ISO and template storage	PVEDatastoreUser (PVEDatastoreAdmin to write)
Bridges and VLANs	PVESDNUser

3. The privilege separation trap

When you create a token in the Proxmox web UI, "privilege separation" is checked by default. Such a token starts with no permissions whatsoever, and the consequences are subtle:

• reads that need privileges return 403;
• endpoints like /storage return 200 with an empty array, no error at all;
• so the panel can only render an empty list, which looks exactly like a broken panel.

To confirm and fix it:

pveum token list                        # privsep = 1 means separation is on
pveum acl modify / --tokens 'panel@pve!panel' --roles PVEVMAdmin   # grant the token directly

The panel's Settings → Environment self-check asks Proxmox for the token's effective permissions (/access/permissions) and lists what is missing together with the command to fix it.

4. The console needs a separate PVE account

Proxmox does not allow an API token to open a VNC console. Those endpoints only accept a ticket derived from a user password, so using the console in the browser means filling in a PVE account in the panel settings as well:

PVE_CONSOLE_USER=root@pam
PVE_CONSOLE_PASSWORD=<that account's password>

Without it the console is disabled and nothing else is affected. This is a Proxmox limitation, not a panel one.

5. Several Proxmox hosts

The panel can store multiple connections and switch between them from the top bar; the switch applies immediately across every page. Create one token per host. Each machine in a list view is labelled with the connection it belongs to.

6. Permission isolation for regular users

• The roles and permissions inside the panel are the panel's own and have nothing to do with PVE roles.
• Virtual machines and containers have an owner: a regular user only sees the machines assigned to them, and an administrator assigns them from the row actions in a list.
• Batch operations check permission and ownership per machine. "Batch" is not a back door around the isolation.

Error reference

Symptom	Cause
Saving a connection reports 401	Token ID or secret copied wrong
Reports 595	Certificate validation failed (turn off "verify SSL" for a self-signed certificate, or supply the CA)
Connection times out	Firewall is not letting port 8006 through
Connects but every list is empty	Privilege separation, see section 3
The console will not open	PVE_CONSOLE_USER / PVE_CONSOLE_PASSWORD are missing, or Nginx is dropping the Upgrade / Connection headers