Depl0y-Custom/docs/PROXMOX_API_TOKENS.md

Proxmox API Tokens for 2FA Authentication

When your Proxmox VE server has Two-Factor Authentication (2FA) enabled, you need to use API Tokens instead of password authentication for programmatic access.

Why API Tokens?

• Bypass 2FA: API tokens don't require 2FA codes, making them perfect for automated systems
• More Secure: Can be revoked without changing your main password
• Fine-grained Permissions: Can be restricted to specific operations
• Audit Trail: API token usage is logged separately

Creating an API Token in Proxmox

Step 1: Log into Proxmox Web Interface

1. Navigate to your Proxmox web interface: https://your-proxmox-host:8006
2. Log in with your credentials (including 2FA if enabled)

Step 2: Navigate to API Tokens

1. Click on Datacenter in the left sidebar
2. Expand Permissions
3. Click on API Tokens

Step 3: Create a New Token

1. Click the Add button at the top

2. Fill in the token details:

   • User: Select the user (e.g., root@pam)
   • Token ID: Give it a meaningful name (e.g., depl0y)
   • Privilege Separation: UNCHECK this box (important!)
     • Unchecking this gives the token the same permissions as the user
     • Checking it would create a token with limited permissions
   • Expiration: Leave empty for no expiration, or set an expiration date

3. Click Add

Step 4: Save the Token Secret

IMPORTANT: After clicking Add, you'll see a screen showing the Token Secret.

Token ID: root@pam!depl0y
Token Secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Copy and save this secret immediately! You won't be able to see it again.

Using API Tokens in Depl0y

When adding a Proxmox host in Depl0y:

1. Go to Proxmox Hosts → + Add Host

2. Fill in basic details:

   • Name: Any name for your reference
   • Hostname/IP: Your Proxmox server address
   • Port: 8006 (default)
   • Username: root@pam (the user who owns the token)

3. Check the box: "Use API Token (recommended for 2FA-enabled Proxmox)"

4. Enter token details:

   • API Token ID: You can use either format:
     • Full format: root@pam!depl0y (the complete Token ID from Proxmox)
     • Short format: depl0y (just the token name)
   • API Token Secret: The UUID-like secret you copied earlier

5. Optionally check "Verify SSL Certificate" if you have a valid SSL cert

6. Click Add Host

Example

If Proxmox shows your token as:

Token ID: root@pam!mytoken
Token Secret: 12345678-1234-1234-1234-123456789abc

In Depl0y, you can enter either:

Option 1 (Full format - Recommended):

• Username: root@pam (can be anything, will be extracted from token)
• API Token ID: root@pam!mytoken
• API Token Secret: 12345678-1234-1234-1234-123456789abc

Option 2 (Short format):

• Username: root@pam
• API Token ID: mytoken
• API Token Secret: 12345678-1234-1234-1234-123456789abc

Troubleshooting

Connection Failed

• Make sure "Privilege Separation" was UNCHECKED when creating the token
• Confirm the token hasn't expired
• Check that the Proxmox host is reachable from your Depl0y server
• Verify the token secret is correct (it's case-sensitive)
• Try using the full token format: root@pam!tokenname

Permission Denied

• Ensure "Privilege Separation" was unchecked when creating the token
• Verify the user account has sufficient permissions
• Check Proxmox logs: /var/log/pve/tasks/

Token Not Working After Creation

• API tokens may need a few seconds to become active
• Try refreshing the Proxmox web interface
• Log out and back in to Proxmox

Security Best Practices

1. Use Separate Tokens: Create different tokens for different applications
2. Set Expiration: Consider setting expiration dates for tokens
3. Revoke Unused Tokens: Regularly audit and remove tokens you no longer use
4. Store Securely: Keep token secrets secure, like passwords
5. Monitor Usage: Check Proxmox logs for API token usage

Revoking a Token

To revoke an API token:

1. Go to Datacenter → Permissions → API Tokens
2. Select the token you want to revoke
3. Click Remove
4. Confirm the removal

The token will be immediately revoked and can no longer be used.