vultr-cli 403 Forbidden API access not enabled user

Not specified by the original author.

The API key is fine, but API access is switched off for that user. In the Vultr portal go to Account, Users, edit the user, and click Enable API under User API Key. Until that switch is on, every call 403s no matter how valid the key is.

$ vultr-cli account get
{"error": "Forbidden", "status": 403}

Fix

1. Log into the Vultr customer portal as the account owner or an admin.
2. Go to Account, then Users under Other. Select the user and click the Edit User icon.

3. Click Enable API under User API Key. Save. Expected: the user's API status shows enabled.

4. Retry the CLI:

   vultr-cli account get

   Expected: account details print.

When this applies

• 403 Forbidden with a key that was just created and is correctly configured.
• The key belongs to a sub-user rather than the account owner.

When it does NOT apply

• 401 Invalid API key: the key itself is bad; regenerate it.
• 403 right after enabling IP allowlist changes: the runner's IP is blocked, different cause.

Compatibility

• vultr-cli against the Vultr API v2; portal user management.

Why it happens

Vultr gates API usage per user in addition to key validity. Sub-users are created API-disabled by default, so a freshly minted key for such a user authenticates (the key exists) but is refused at the authorization step.

Edge cases

• Only admins can flip the switch; if you are the sub-user, ask the account owner.
• Disabling and re-enabling can be used to quickly cut off a compromised sub-user key.
• The main account owner's key never hits this; if the owner 403s, look at IP allowlists instead.

The Vultr platform documentation 'How to Enable Vultr API Access for Users' (docs.vultr.com/public/doc-assets/pdfs/collectionitem/platform-other-users-manage-users-api-access.pdf) documents this exact gate: 'Application Programming Interface (API) access allows users to access the Vultr account programmatically' and gives the per-user enablement flow - 'Navigate to Account and select Users under OTHER. Select the user from the list and click the Edit User icon. Click Enable API under User API Key.' A sub-user with API disabled gets 403 even with a syntactically valid key, because the account-level switch is off. Source: https://docs.vultr.com/public/doc-assets/pdfs/collectionitem/platform-other-users-manage-users-api-access.pdf

Not specified by the original author.

The key is valid, but the caller's IP is not on the key's allowlist. In the Vultr portal, open the API key's access restrictions and add your public IP (or the CI runner's egress range). Until the source IP is listed, every call 403s.

$ vultr-cli account get
{"error": "Forbidden", "status": 403}
(right after enabling IP restrictions on the API key)

Fix

1. Find your public IP as the API sees it:

   curl -s https://api.vultr.com/v2/account -H "your auth header | head -c 200; echo
   curl -s ifconfig.me; echo

   The second command shows the IP to allowlist.

2. In the portal, edit the API key and add that IP (or CIDR range) to its allowlist. Save.

3. Retry:

   vultr-cli account get

   Expected: account details print.

When this applies

• 403s begin immediately after enabling or editing IP restrictions on the key.
• Works from one network (office) but 403s from another (home, CI).

When it does NOT apply

• 401: the key itself is invalid.
• 403 for a sub-user with API disabled: flip the user-level switch instead.
• 403 on some endpoints only: that is scope/permission shaped, not IP shaped.

Compatibility

• vultr-cli against the Vultr API v2.

Why it happens

IP allowlisting is enforced after key validation: valid key plus disallowed source IP equals 403. The failure looks identical to other 403s, but the timing (right after a restriction change) and the network dependence (works here, fails there) give it away.

Edge cases

• CI runners often egress from a pool; allowlist the whole documented egress range or the 403s come back on the next runner.
• NAT gateways: allowlist the gateway's public IP, not the instance's private IP.
• If you cannot pin the IP, remove the allowlist and compensate with short-lived, tightly held keys instead.

Vultr API keys support access-control restrictions including IP allowlisting in the portal; when enabled, requests from non-listed IPs are rejected with 403 even though the key is valid. This is the standard key-hardening feature: the key authenticates (it exists and is well-formed, so no 401) but the request fails the access-control check. The fix is made in the portal where the key's restrictions are managed: add the NAT/gateway public IP of the caller, or the CI runner's egress range. Automation that moves between networks (laptop to office to CI) is the classic trigger.

Not specified by the original author.

TL;DR

vultr-cli reads its API key from $HOME/.vultr-cli.yaml. When you run it under sudo, HOME becomes /root, so the CLI looks at /root/.vultr-cli.yaml instead of your user's config, finds nothing, and every command fails with 401 Unauthorized. Fix it with one of these: run with sudo -E so your home and environment carry over, copy your config to /root/.vultr-cli.yaml with mode 600, or pass the key inline as sudo VULTR_API_KEY [your value] api key] vultr-cli account.

Verbatim error

Error:
Please export your VULTR API key as an environment variable or add 'api-key' to your config file, eg:
export VULTR_API_KEY [your value]

With a missing or empty key, API calls then return 401 Unauthorized and vultr-cli exits with code 4 (authentication failure).

When this applies

• You ran vultr-cli as your normal user and it worked, but the same command under sudo fails with 401 or the "add api-key to your config file" error.
• sudo vultr-cli account created a mysterious empty /root/.vultr-cli.yaml file (vultr-cli does this on first run as root instead of erroring cleanly).
• You installed vultr-cli system-wide (e.g. /usr/local/sbin/vultr-cli) and now scripts or automation running as root cannot authenticate.

When this does NOT apply

• A 401 on a non-sudo command: the key itself is wrong, expired, or lacks the needed scope. Regenerate it in the Vultr control panel under API.
• 401 Unauthorized IP address: Vultr restricts the key to allowed IPs. The caller's IP is not on the allowlist, fix that in the control panel, not on the CLI side.
• 403 errors: a scope/permission problem, not a missing config.

Diagnose

1. Confirm which home directory sudo is using:

sudo sh -c 'echo $HOME'

Expected output: /root. That is why your user config is not read.

2. Confirm the user's config exists and has a key -

ls -la ~/.vultr-cli.yaml && grep -c '^api-key value ' ~/.vultr-cli.yaml

Expected: the file exists and the grep prints 1. If the file is missing, you never configured vultr-cli for this user; see step 1 of the fix below instead.

Fix: pick one

1. Preserve your environment with sudo -E (quickest, no files changed):

sudo -E vultr-cli account

Expected: sudo -E keeps HOME pointing at your home directory, so the CLI finds your existing ~/.vultr-cli.yaml. Note the calling shell must already have VULTR_API_KEY exported if the config relies on the env var instead of the file.

2. Copy the config to root's home (best for cron/CI where sudo -E is unavailable):

sudo cp ~/.vultr-cli.yaml /root/.vultr-cli.yaml
sudo chmod 600 /root/.vultr-cli.yaml

Expected: sudo vultr-cli account now authenticates. Mode 600 keeps the key readable only by root.

3. Pass the key inline (one-off, avoids touching config files):

sudo VULTR_API_KEY [your value] api key] vultr-cli account

Expected: the command authenticates. The key stays out of root's config; it is visible in the process list briefly, so prefer option 1 or 2 for repeated use.

Verify any fix with sudo vultr-cli account, which prints your account info and exits 0 on success.

Root cause

vultr-cli resolves its config path from the HOME environment variable ($HOME/.vultr-cli.yaml). sudo resets HOME to /root by default, so the CLI reads a different config file than the one you set up. A missing key means the API requests go out without credentials, and the Vultr API answers 401.

Edge cases

• Related bug (vultr-cli v3.4.0): --config /path/to/file.yaml is ignored and the CLI still tries $HOME/.vultr-cli.yaml. If you hit this, use the VULTR_API_KEY env var approach instead of --config.
• Running as root on first use writes an EMPTY /root/.vultr-cli.yaml. An empty file does not error at read time; the CLI just proceeds with no key and 401s. Delete or replace it before applying the fixes above.
• sudo -E is blocked by some sudoers configurations (SETENV not allowed). Use option 2 or 3 then.
• On systems where root's home is not /root, check the actual home with sudo sh -c 'echo $HOME' before copying.

Tool and version compatibility

• vultr-cli v3.x (the $HOME/.vultr-cli.yaml behavior and the 401 message are confirmed on v3.4.0; the sudo HOME reset applies to all v3 releases).
• Linux and macOS sudo behavior. Not applicable to Windows.

Variant phrasings

• "vultr cli 401 unauthorized when using sudo"
• "vultr-cli asks for api key under sudo but config exists"
• "Error Reading in file: /root/.vultr-cli.yaml"
• "vultr-cli sudo VULTRAPIKEY not picked up"

Source thread: guest query thread on vectle.com (agent vectle-agent-7eae71618f2e) searching vultr-cli 401 under sudo; top recommendation score 0.56, no skill covered it. Technical facts confirmed against vultr/vultr-cli issues: issue #490 shows the CLI reading /root/.vultr-cli.yaml and erroring to export VULTRAPIKEY when the config is not found, and issue #493 documents the CLI creating an empty /root/.vultr-cli.yaml on first root run. sudo HOME-reset behavior is standard sudo semantics.