Proxmox Deep Dive Part 12: Users, Permissions, and the API

Part 11 covered hardware passthrough. This part covers the permission model underneath everything in this series, and the automation tooling that builds directly on top of it, which matters more here than in most homelab software because Part 1 already established that the GUI and the API are genuinely the same thing.

Realms: where a user’s identity actually comes from.

Every Proxmox user belongs to a realm, which determines how that user authenticates. The two built-in realms are pam (ordinary Linux system users on the host itself) and pve (Proxmox’s own separate user database, unrelated to system accounts). Beyond those two, Proxmox supports LDAP, Microsoft Active Directory, and OpenID Connect as external realms, letting an existing identity provider handle authentication rather than maintaining a separate Proxmox-only user list, useful once a homelab’s user management is already centralized somewhere else.

Roles, paths, and ACLs: the three pieces that combine into an actual permission.

A role is a named bundle of privileges, PVEAdmin and PVEVMAdmin are built-in examples, and custom roles can be defined from the full privilege list directly. A path is a location in Proxmox’s resource tree, a specific VM, a storage definition, an entire node, or the whole cluster. An ACL binds a user (or a token, covered next) to a role on a specific path, and that binding can be scoped as narrowly as one VM or as broadly as the whole datacenter. The actual permission a user has at any point is the sum of every ACL binding that applies to them, evaluated across the resource tree, which is what lets a single homelab user account be, say, a full admin on their own personal VMs and read-only on someone else’s, rather than an all-or-nothing choice.

API tokens: scoped, stateless, and deliberately less powerful than the user they belong to.

An API token is generated for a specific user and provides stateless access to most of the REST API, notably excluding the VM/system console endpoints, which can’t be reached via a token regardless of the permissions granted. Tokens get their own separate expiration date and, critically, their own separate ACLs, and by default a new token has no permissions at all until explicitly granted some. The permission that actually applies to a token’s requests is the intersection of the user’s own permissions and the token’s own ACLs, a token can never do something its backing user isn’t themselves allowed to do, no matter what the token’s own ACL says, which is the mechanism that keeps a leaked token’s blast radius bounded even if it was created with an overly broad ACL by mistake. Scoping every automation token down to exactly what the automation needs, rather than reusing a broad admin token everywhere, is the practical takeaway.

Terraform: the current state of the ecosystem.

The bpg/proxmox Terraform (and OpenTofu) provider has become the de facto standard for Proxmox infrastructure-as-code, actively maintained, at v0.101.0 as of this writing, spanning 111 resources and 87 data sources across VMs, LXC containers, networking, storage, and more, and now generally recommended over the older Telmate provider, which sees less active maintenance. Both authenticate against the same API token model just described, which is the whole point, Terraform isn’t a special integration Proxmox built for it, it’s an ordinary API client using the same scoped-token mechanism any automation should use.

Ansible: the configuration-management half of the same story.

The community.general.proxmox modules cover the Proxmox side of Ansible automation, and support the same token-based authentication as Terraform, meaning credentials don’t have to differ between the two tools if a homelab uses both. The natural division of labor, and the one this site’s own Ansible Deep Dive series covers in depth for the configuration-management side specifically, is Terraform provisioning the VM or container itself against the Proxmox API, then Ansible configuring what runs inside it once it exists, two tools solving different halves of the same “build a homelab from code” problem rather than competing for the same job.

Part 13 closes the series: monitoring the whole stack with Prometheus and Grafana, ongoing maintenance, and a homelab best-practices checklist pulling every part of this series together.