An API token lets Aprox sign in without your password. Tokens never prompt for a two-factor code, keep working in the background for alerts, widgets and the watch, and can be limited to exactly the rights you want Aprox to have. The one thing a token cannot do is open a console: Proxmox accepts only password sign-ins for console access.

You create the token on the server, then enter it in Aprox. This article covers both Proxmox VE and Proxmox Backup Server.

Create a token in Proxmox VE

In the web interface

  1. In the Proxmox VE web interface, go to Datacenter › Permissions › API Tokens and click Add.
  2. Choose the User the token belongs to, for example root@pam.
  3. Enter a Token ID, for example aprox.
  4. Decide on Privilege Separation:
    • On: the token starts with no rights. You give it rights of its own in the next section. This is the safer choice.
    • Off: the token has the same rights as its user.
  5. Click Add.
  6. Copy the Secret. Proxmox shows it only once.

On the command line

You can do the same on any node with pveum:

pveum user token add root@pam aprox --privsep 1

The command prints the token's full ID and its secret. Copy the secret.

Give a privilege-separated token its rights

A privilege-separated token needs permissions of its own. They can never exceed the rights of its user.

  1. Go to Datacenter › Permissions and click Add › API Token Permission.
  2. Choose the Path, for example / for the whole cluster.
  3. Choose the API Token, for example root@pam!aprox.
  4. Choose a Role. For example:
    • PVEAuditor to look at everything without changing anything;
    • PVEVMAdmin on /vms to manage guests;
    • Administrator on / for everything Aprox can do.
  5. Leave Propagate on and click Add.

On the command line:

pveum acl modify / --tokens 'root@pam!aprox' --roles PVEAuditor

When the token lacks a right, Aprox says so and names it, for example "It needs the VM.Config.Disk privilege…". Aprox adds: "An API token also has to be granted that privilege itself, or be marked as having the user's full rights."

Use the token in Aprox

  1. Add the server, or edit it: long-press or right-click the server › Edit.
  2. Under Authentication, set Method to API Token.
  3. Enter the Username without the realm, for example root.
  4. Choose the Realm, for example pam.
  5. Enter the Token name, for example aprox. This is the part after the !.
  6. Paste the Token secret.
  7. Check the Token ID. It must match the token's full ID in Proxmox, for example root@pam!aprox.
  8. Tap Save.

The editor's footer reminds you: "Create the token in Proxmox under Datacenter → Permissions → API Tokens. The secret is shown only once. Tokens never expire and can be privilege-separated, but Proxmox does not accept them for console access — use password login if you need the console."

Typical privileges per feature

Aprox can only do what the token or user is allowed to do. These are the standard Proxmox VE privileges that the features typically need. Grant them on / or on the paths you want Aprox to manage.

Feature in Aprox Typical Proxmox privileges
Browse everything, charts, tasks, backup jobs Sys.Audit, VM.Audit, Datastore.Audit (the PVEAuditor role on /)
Guest power actions VM.PowerMgmt
Console VM.Console for guests, Sys.Console for the node shell; password sign-in only
Hardware editing VM.Config.*, for example VM.Config.Disk
Snapshots VM.Snapshot, plus VM.Snapshot.Rollback to roll back
Back up now and restore VM.Backup (plus VM.Allocate to restore), and Datastore.AllocateSpace on the storage
Clone, create and destroy guests VM.Clone, VM.Allocate, Datastore.AllocateSpace
Migrate VM.Migrate
Guest firewall VM.Config.Network
Node restart, shutdown and Wake-on-LAN Sys.PowerMgmt
Refresh the package index, restart services Sys.Modify
Disks and SMART Sys.Audit
Upload, download from a URL, appliance templates Datastore.AllocateTemplate (download from a URL also needs Sys.Audit and Sys.Modify on the node)
Stop a task Sys.Modify on the node, or the task must be your own

Create a token in Proxmox Backup Server

In the web interface

  1. In the Proxmox Backup Server web interface, go to Configuration › Access Control › API Token and click Add.
  2. Choose the User and enter a Token Name, for example aprox.
  3. Click Add and copy the secret. It is shown only once.
  4. Go to Configuration › Access Control › Permissions and add an API Token Permission for the new token. A new token has no permissions at all. For example:
    • Audit on / to look at everything;
    • DatastoreAdmin on /datastore to manage backups;
    • Admin on / for everything.

On the command line

proxmox-backup-manager user generate-token root@pam aprox
proxmox-backup-manager acl update / Audit --auth-id 'root@pam!aprox'

In Aprox

  1. Set Type to Backup Server and Method to API Token.
  2. Enter the Username and choose the Realm.
  3. Enter the Token name and the Token secret.
  4. Tap Save.

Enter only the secret. Aprox joins it to the token ID the way Backup Server expects, which differs from Proxmox VE.

Typical Backup Server privileges:

Feature in Aprox Typical privileges
Browse datastores and backups Datastore.Audit, Datastore.Backup
Prune and garbage collection Datastore.Modify, Datastore.Prune
Verify Datastore.Verify
System (updates, services, power) Sys.Audit, Sys.Modify, Sys.PowerManagement
Access Control (users, tokens, permissions) Permissions.Modify

You can also create Backup Server tokens from inside Aprox once you are signed in with an account that may manage users. This needs Aprox Pro. See Users, API tokens and permissions.

Good to know

Warning

Treat the token secret like a password. Anyone who has it can do everything the token is allowed to do. If a secret leaks, delete or regenerate the token on the server.

  • A token you delete on the server stops working in Aprox at once. Aprox then reports "Proxmox rejected the credentials for this server."
  • The console needs a password sign-in. If you need it, switch the server's Method to Password.