Proxmox VE

Thinfinity® Cloud Manager connects to Proxmox Virtual Environment using the Proxmox API over HTTPS. Authentication is handled via an API token scoped to a dedicated Proxmox user, or via username/password. This article documents the Cloud Manager credential form for Proxmox, the minimum Proxmox privileges, and common configuration errors.

Info

All API calls from Cloud Manager originate from the Thinfinity® Workspace server. Ensure outbound HTTPS (port 8006) is open from that host to the Proxmox VE server. See Prerequisites for the full network requirements.

Prerequisites

Before adding Proxmox credentials in Cloud Manager, the following must be in place on the Proxmox side:

Proxmox VE is installed and accessible via the web interface at https://<proxmox-host>:8006.
A dedicated Proxmox user exists for Cloud Manager in the PVE realm (Proxmox VE authentication server). Cybele Software recommends a dedicated user rather than the root@pam account. Proxmox API tokens do not support PAM realm users — use the pve realm.
A custom Proxmox role exists with the privileges listed in Minimum Proxmox Privileges below, and that role is assigned to the user, with Propagate enabled.
(Recommended) An API Token has been generated for the user, with Privilege Separation disabled so the token inherits the user’s permissions. The token secret is shown only once at creation — store it in a secrets manager.
The Proxmox API is reachable from the Workspace server on port 8006.

For how to create users, roles, permission assignments, and API tokens, refer to the Proxmox VE User Management documentation.

Minimum Proxmox Privileges

The custom role assigned to the Cloud Manager user must include the following privileges.

Privilege	Required For
`VM.Audit`	All operations — list and read VM configuration and status
`VM.PowerMgmt`	All operations — start, stop, reset, and suspend virtual machines
`VM.Config.Options`	All operations — modify VM options for some provisioning operations
`Datastore.Audit`	All operations — browse datastores and read storage usage
`VM.Clone`	VDI/DaaS Models only — clone virtual machines
`VM.Allocate`	VDI/DaaS Models only — create and delete virtual machines
`Datastore.AllocateSpace`	VDI/DaaS Models only — allocate storage for new VMs

Info

For Managed VMs only (no provisioning of new VMs from VDI/DaaS Models), the privileges marked “VDI/DaaS Models only” can be omitted.

Authentication Method

Cloud Manager authenticates to Proxmox with a user/realm and a single secret field, which accepts either a Proxmox password or an API token secret. API tokens are recommended for production — they can be revoked without changing the user password, and with Privilege Separation they can also be scoped independently. The credential form does not have a separate token field; the authentication method is determined by the format of the User field.

Add the Credentials in Cloud Manager

In Cloud Manager, go to Credentials and click + New.
Select Proxmox as the provider.
Fill in the fields below and click Save.

For the full Add / Edit / Delete procedure, see Managing Credentials.

Proxmox Credential Fields

Field	Description
Proxmox API URL	The full HTTPS URL of the Proxmox API endpoint. Standard format: `https://<proxmox-host>:8006/api2/json/`. Cloud Manager validates that the URL ends in `/api2/json` — a credential without that path will not save.
User	The Proxmox user identifier. For password authentication, use `username@realm` format (e.g., `thinfinity-cm@pve`). For API token authentication, use `username@realm!token-id` (e.g., `thinfinity-cm@pve!cloudmanager`).
Password	The user’s password or the token secret value, depending on the format used in the User field. Cloud Manager uses a single secret field for both authentication methods — there is no separate token field.
Disable TLS Verification	If enabled, Cloud Manager skips SSL certificate validation for the Proxmox API connection. Only use this in isolated, fully trusted networks. In production, install a certificate signed by a trusted CA on Proxmox.

Warning

Enabling Disable TLS Verification exposes the connection to potential man-in-the-middle attacks. This is common in Proxmox lab environments where the default self-signed certificate is in use, but should not be used in production. Install a certificate signed by a trusted CA on Proxmox to avoid this option.

Verification

After saving, Cloud Manager validates the credentials by connecting to the Proxmox API and listing the VM inventory across all nodes in the cluster. If validation succeeds, the credential status shows as Ok.

Common Errors

Error	Likely Cause	Resolution
`401 Unauthorized`	Incorrect username format, password, or the API token has been revoked.	Verify the user format is `username@realm` (for password auth) or `username@realm!token-id` (for token auth). Check the token status in Proxmox.
`403 Forbidden`	The user or token lacks the required privileges.	Verify the role assignment in Proxmox. Ensure Propagate is enabled, and check the role against the Minimum Proxmox Privileges table.
`Connection refused` / `SSL error`	The API URL is malformed, the port is incorrect, or the TLS certificate is untrusted.	Verify the URL format including the trailing `/api2/json/`. Enable Disable TLS Verification if the host uses a self-signed certificate.
FQDN resolution failure	The Workspace server cannot resolve the Proxmox hostname.	Use the IP address in the API URL, or verify DNS resolution from the Workspace server.

Security Recommendations

Use API tokens instead of username/password for all automated integrations. Tokens can be revoked without changing the user password.
Enable Privilege Separation on the token if you want granular control over what the token can do independently of the user’s permissions. With Privilege Separation enabled, assign permissions to the token directly.
Use a certificate signed by a trusted CA on Proxmox to avoid the need for the Disable TLS Verification option.
Restrict API access using Proxmox firewall rules to allow connections to port 8006 only from the Thinfinity® Workspace server IP.

See Also