How to Create a Proxmox API Token for Mobile Apps

Why API Tokens Are Better Than Passwords for Mobile Apps

When you connect a mobile app like ProxmoxR to your Proxmox VE server, you have two authentication options: a username and password, or an API token. While both work, API tokens are the superior choice for mobile management and here is why.

A password is shared across every session and device that uses it. If you need to revoke access from your phone — say the device is lost or stolen — changing the password logs you out of everywhere, including the web UI and any scripts using those credentials. An API token, on the other hand, is an independent credential tied to a specific user. You can create multiple tokens, one per device, and revoke any individual token without affecting anything else. The token also never expires your active web sessions.

API tokens can also be configured to respect or bypass the user's permissions, giving you fine-grained control over what the mobile app can do. This guide walks you through creating and configuring a Proxmox API token for use with ProxmoxR, from scratch.

Step 1: Create a Dedicated User

Do not use your root account or your personal admin account for the mobile app. Create a dedicated user so you can track its activity separately and control its permissions independently.

SSH into your Proxmox server and run:

# Create a new user in the Proxmox VE authentication realm
pveum user add mobileapp@pve -comment "ProxmoxR Mobile App"

# Set a password (required for the account, even though the app will use a token)
pveum passwd mobileapp@pve

The @pve realm means this user is managed by Proxmox's built-in authentication. You could also use @pam if you prefer Linux system authentication, but @pve is simpler and does not require a corresponding Linux user.

Step 2: Create a Role with Appropriate Permissions

Proxmox uses role-based access control. You assign a role to a user on a specific path (resource scope) to grant permissions. Proxmox ships with several built-in roles:

• PVEAdmin — Full administrative access to VMs, containers, storage, and configuration. Use this if you want full management from your phone.
• PVEAuditor — Read-only access. Use this for monitoring-only setups where you want to view but not change anything.
• PVEVMAdmin — Can manage VMs and containers but not nodes, storage, or system configuration.

For most ProxmoxR users who want full mobile management, PVEAdmin is the right choice. For a monitoring-only dashboard, PVEAuditor is sufficient.

Step 3: Assign the Role to Your User

Grant the role on the root path (/) to give the user access to all resources, or on a specific path to limit the scope:

# Full management access to everything
pveum acl modify / -user mobileapp@pve -role PVEAdmin

# Or, restrict to a specific node
pveum acl modify /nodes/pve1 -user mobileapp@pve -role PVEAdmin

# Or, restrict to a specific VM only
pveum acl modify /vms/100 -user mobileapp@pve -role PVEVMAdmin

The path-based permission system is powerful. If you have a multi-node cluster but only want the mobile app to manage VMs on one node, you can scope it precisely.

Step 4: Create the API Token

Now create an API token for the user. This is the credential you will enter in ProxmoxR:

# Create the API token
pveum user token add mobileapp@pve mobile-token -privsep 0

The output will look something like this:

┌──────────────┬──────────────────────────────────────────────┐
│ key          │ value                                        │
├──────────────┼──────────────────────────────────────────────┤
│ full-tokenid │ mobileapp@pve!mobile-token                   │
│ info         │ {"privsep":"0"}                               │
│ value        │ a1b2c3d4-e5f6-7890-abcd-ef1234567890         │
└──────────────┴──────────────────────────────────────────────┘

Important: Copy the token value immediately. It is displayed only once and cannot be retrieved later. If you lose it, you must delete the token and create a new one.

The -privsep 0 flag means the token inherits the user's permissions. If you set -privsep 1 (the default), you need to assign separate permissions to the token itself, which adds an extra layer of control but also more configuration.

Step 5: Enter the Token in ProxmoxR

Open ProxmoxR on your phone and add a new server connection. You will need three pieces of information:

• Hostname or IP — Your Proxmox server's address (for example, 192.168.1.100 or proxmox.local)
• Token ID — The full token ID in the format mobileapp@pve!mobile-token
• Token Secret — The value string you copied in the previous step

ProxmoxR will connect to your server on port 8006 and verify the token. If the connection succeeds, you will see your nodes, VMs, and containers appear in the app.

Step 6: Test the Connection

After adding the server, verify that everything works correctly:

• Check that all nodes appear in the cluster view
• Navigate to a VM and confirm you can see its status and resource graphs
• If you assigned a management role, try a non-destructive action like viewing a VM's configuration
• If you assigned a read-only role, verify that action buttons are appropriately restricted

Optional: Create a Read-Only Token for Monitoring

If you want a second connection in ProxmoxR that is strictly for monitoring — no ability to start, stop, or modify anything — create a separate user and token with the PVEAuditor role:

# Create a monitoring-only user
pveum user add monitor@pve -comment "Read-Only Monitoring"

# Assign read-only role
pveum acl modify / -user monitor@pve -role PVEAuditor

# Create the token
pveum user token add monitor@pve view-token -privsep 0

This is useful if you want to hand your phone to a colleague to show them your infrastructure without risking accidental changes, or if you simply want a safe dashboard to glance at throughout the day.

Security Tips for API Tokens

One Token Per Device

Create a separate token for each device that connects to your Proxmox server. Name them descriptively — iphone-token, ipad-token, work-phone-token. If any device is lost or compromised, you revoke only that device's token:

# Revoke a specific token
pveum user token remove mobileapp@pve iphone-token

Revoke Tokens When Devices Are Lost

If a device with ProxmoxR is lost or stolen, immediately revoke its API token from the Proxmox web UI or command line. The token is stored in the device's secure storage (iOS Keychain or Android Keystore), which is encrypted and protected by biometrics, but revoking the token server-side ensures it cannot be used even if someone extracts it.

Audit Token Usage

Review API access logs periodically to verify that tokens are only being used from expected IP addresses:

# Check recent API access
tail -100 /var/log/pveproxy/access.log | grep mobileapp

Conclusion

Setting up a Proxmox API token for ProxmoxR takes about five minutes and significantly improves your security posture compared to using a password. You get individual revocation, scoped permissions, and clean audit trails. Create a dedicated user, assign the right role, generate the token, and enter it in ProxmoxR — your mobile Proxmox management is now both functional and secure.