Skip to content

Create the Proxmox API Token

Create a dedicated PVE user and API token for the panel. Do not use root@pam.

On any cluster node (the Datacenter → Permissions UI does the same):

# Dedicated user (pve realm — no PAM/Linux account needed)
pveum user add pterocloud@pve --comment "PteroCloud panel integration"

# Least-privilege role (see permissions.md for the full matrix)
pveum role add PteroCloud -privs "VM.Audit VM.PowerMgmt Datastore.Audit Sys.Audit"

# Grant the role cluster-wide (or scope it: --path /nodes/pve01, /vms/101, …)
pveum acl modify / --users pterocloud@pve --roles PteroCloud

# API token. Privilege separation OFF is recommended: the token then carries
# exactly the user's ACLs, and the role above stays the single source of truth.
pveum user token add pterocloud@pve panel --privsep 0

The command prints the token id and the secret:

token id:  pterocloud@pve!panel
secret:    YOUR_PROVIDER_TOKEN   (shown ONCE — copy it now)

The token secret is a credential

Copy the secret into the panel immediately. It is shown once. Never paste it into a ticket, a screenshot or a log. This documentation uses the placeholder YOUR_PROVIDER_TOKEN.

Read-only tokens

A read-only connection (monitoring/inventory only, no power actions) can drop VM.PowerMgmt from the role; combine with the panel-side read_only flag for defense in depth.

Rotating a token

Rotation is validate-first: the new pair is tested against the provider, and only a working pair is persisted.

  1. Create a new token: pveum user token add pterocloud@pve panel2 --privsep 0.
  2. Rotate in the panel: Provider view → Rotate Credentials (or POST /api/application/pterocloud/providers/{uuid}/credential).
  3. Delete the old token in PVE: pveum user token remove pterocloud@pve panel.

Rotation is rejected on read-only connections.