ProxmoxAPIToken

Every monitoring tool that talks to Proxmox needs authentication. API tokens are the right choice over password auth -- they're scoped to specific permissions, independently revocable, and don't require storing a user password in plaintext on your monitoring box.

Quick Setup (CLI)

SSH into any Proxmox node and run these four commands as root:

# 1. Create a dedicated monitoring user
pveum user add monitoring@pve -comment "Monitoring read-only user"

# 2. Create a role with only audit (read-only) privileges
pveum role add monitoring -privs "VM.Audit,Datastore.Audit,Sys.Audit,SDN.Audit"

# 3. Assign the role at the root path (covers all nodes, VMs, storage)
pveum aclmod / -user monitoring@pve -role monitoring

# 4. Create API token with privilege separation DISABLED
pveum user token add monitoring@pve monitoring --privsep 0

The last command outputs something like:

┌──────────────┬──────────────────────────────────────┐
│ key          │ value                                │
╞══════════════╪══════════════════════════════════════╡
│ full-tokenid │ monitoring@pve!monitoring             │
│ info         │ {"privsep":"0"}                      │
│ value        │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │
└──────────────┴──────────────────────────────────────┘

Copy the value field immediately. This is the token secret. Proxmox shows it exactly once. If you lose it, delete the token and create a new one.

The full-tokenid (monitoring@pve!monitoring) is the token ID. The value is the secret. These are different things -- monitoring tools need both.

Quick Setup (Web UI)

If you prefer clicking over CLI:

Create the user:

1. Open the Proxmox web UI
2. Go to Datacenter > Permissions > Users
3. Click Add, set User name to monitoring, Realm to Proxmox VE authentication server (pve)
4. No password needed (token auth doesn't use the user password)

Create the role:

1. Go to Datacenter > Permissions > Roles
2. Click Create
3. Name: monitoring
4. Check: VM.Audit, Datastore.Audit, Sys.Audit, SDN.Audit

Assign the role:

1. Go to Datacenter > Permissions
2. Click Add > User Permission
3. Path: /, User: monitoring@pve, Role: monitoring, Propagate: checked

Create the token:

1. Go to Datacenter > Permissions > API Tokens
2. Click Add
3. User: monitoring@pve, Token ID: monitoring
4. Uncheck "Privilege Separation" -- this is critical, see below
5. Click Add and immediately copy the token secret

The Privilege Separation Gotcha

This is the single most common cause of mysterious 401 errors.

By default, Proxmox creates API tokens with privilege separation enabled. This means the token gets its own empty permission set, completely independent of the user's permissions. Your monitoring@pve user has VM.Audit at the root path. The token has nothing. The API returns 401 and the error message gives you no clue why.

The fix: create the token with privilege separation disabled (--privsep 0 on CLI, or uncheck "Privilege Separation" in the web UI). With privsep off, the token inherits the user's permissions directly. No extra step.

Already created a token with privsep on? You can't change it after creation. Delete the token and create a new one with privsep disabled:

# Delete the old token
pveum user token remove monitoring@pve monitoring

# Create new one with privsep off
pveum user token add monitoring@pve monitoring --privsep 0

(There is a use case for privsep-enabled tokens -- when you want a token with fewer permissions than the user, like a write-capable user issuing a read-only token. For monitoring, the user is already read-only, so privsep just adds friction.)

What Each Permission Does

All four are read-only. The monitoring user cannot start, stop, modify, or delete anything. If your monitoring tool only needs VM data, you could skip SDN.Audit, but including it doesn't hurt and covers tools that request broader access.

Verifying It Works

Test the token directly against the Proxmox API:

curl -k -H "Authorization: PVEAPIToken=monitoring@pve!monitoring=YOUR_TOKEN_SECRET" \
  https://YOUR_PVE_HOST:8006/api2/json/version

Expected response:

{"data":{"version":"8.3.2","release":"8.3","repoid":"..."}}

If you get {"data":null} or a 401 error, see Troubleshooting below.

To verify the token can see your VMs:

curl -k -H "Authorization: PVEAPIToken=monitoring@pve!monitoring=YOUR_TOKEN_SECRET" \
  https://YOUR_PVE_HOST:8006/api2/json/cluster/resources?type=vm

This should return a JSON array of your VMs and LXC containers with status, CPU, memory, and disk info.

Troubleshooting

401 Unauthorized:

1. Is privilege separation disabled? This is almost always the cause. Check in Datacenter > Permissions > API Tokens -- the privsep column should show No.
2. Is the token value correct? It's the UUID-format secret, not the token ID. The token ID is monitoring@pve!monitoring. The secret is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
3. Does the user exist? pveum user list | grep monitoring
4. Does the user have the role at path /? pveum acl list
5. Does the role have the right privileges? pveum role list | grep monitoring

403 Forbidden:

• The token authenticated but lacks permission for the requested resource. Usually means the ACL assignment is on a specific path (like /vms/100) instead of the root /. Re-run: pveum aclmod / -user monitoring@pve -role monitoring

Connection refused / timeout:

• Proxmox API runs on port 8006 over HTTPS. Check: curl -k https://YOUR_PVE_HOST:8006
• If the monitoring host and Proxmox are on different subnets, check firewall rules for port 8006
• Verify the IP is correct (not localhost -- the IP your monitoring host can reach)

SSL certificate errors:

• Default Proxmox installs use self-signed certificates. Your monitoring tool needs SSL verification disabled. For PVE Exporter: PVE_VERIFY_SSL=false. For curl: -k flag.

Using the Token

PVE Exporter (Prometheus)

PVE_USER=monitoring@pve
PVE_TOKEN_NAME=monitoring
PVE_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PVE_VERIFY_SSL=false

Generic API Call

curl -k -H "Authorization: PVEAPIToken=monitoring@pve!monitoring=TOKEN_SECRET" \
  https://PVE_HOST:8006/api2/json/ENDPOINT

The PVEAPIToken header format is USER!TOKENID=SECRET. No Bearer prefix.

Multi-Cluster

Each independent Proxmox installation needs its own token. The token created on one cluster does not work on another. For clustered nodes (joined via pvecm), create the token on any single node -- it replicates across the cluster automatically.

For the full Prometheus + Grafana + PVE Exporter setup with pre-built dashboards and alert rules, see the Monitoring Proxmox with Grafana guide.