proxmox/docs/04-configuration/PROXMOX_API_SECRETS_DOTENV.md

# Proxmox API Secrets and Dotenv

**Purpose:** How Proxmox API tokens and related secrets are stored for automation (dotenv).

---

## Where secrets live

- **Repo root:** `/.env` — used by scripts run from the repo (validation, mcp-proxmox, maintenance). **Do not commit** (`.env` is in `.gitignore`).
- **Template:** `/.env.example` — placeholders only; copy to `.env` and fill, or run the token script below.

---

## Proxmox API token (for API automations)

Scripts that call the Proxmox REST API (e.g. `scripts/lib/proxmox-api.sh`, `scripts/validation/validate-config-files.sh`, mcp-proxmox) expect:

| Variable | Example | Description |
|----------|---------|-------------|
| `PROXMOX_HOST` | `proxmox-api.d-bis.org` | Proxmox host or Cloudflare Access entrypoint. |
| `PROXMOX_PORT` | `8006` | API port. |
| `PROXMOX_USER` | `root@pam` | User for the token. |
| `PROXMOX_TOKEN_NAME` | `proxmox-workspace-api` | Bare token name is preferred; helpers also accept a full token id such as `root@pam!proxmox-workspace-api`. |
| `PROXMOX_TOKEN_VALUE` | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Token secret (UUID). |

**Authorization header:** `PVEAPIToken=${PROXMOX_USER}!${bare_token_name}=${PROXMOX_TOKEN_VALUE}`

If `PROXMOX_TOKEN_NAME` already contains the full token id (`user@realm!token-name`), active helpers in this repo normalize it or pass it through correctly so the auth header is not double-prefixed.

---

## Obtain token and store in .env

**Option A — Script (recommended):** From repo root, with SSH to the Proxmox host:

```bash
./scripts/proxmox/create-and-store-proxmox-api-token.sh
```

This creates a new API token on the host, parses the secret from the one-time output, and updates `/.env` with `PROXMOX_HOST`, `PROXMOX_USER`, `PROXMOX_TOKEN_NAME`, `PROXMOX_TOKEN_VALUE`. Use `--no-update-env` to only print the values.

**Option B — Manual:** In Proxmox UI: **Datacenter → Permissions → API Tokens → Add**. Create token, copy the secret once, then set in `.env`:

```bash
PROXMOX_HOST=proxmox-api.d-bis.org
PROXMOX_PORT=8006
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=<paste-secret-here>
```

---

## Other API secrets (dotenv)

Other automation secrets are also stored in the repo root `.env` (see `/.env.example`):

- **NPMplus:** `NPM_EMAIL`, `NPM_PASSWORD`, `NPM_URL`, etc.
- **Cloudflare:** `CLOUDFLARE_API_TOKEN` or `CLOUDFLARE_EMAIL` + `CLOUDFLARE_API_KEY`, zone IDs, tunnel tokens.
- **Gitea:** `GITEA_TOKEN`, `GITEA_URL`.
- **Fastly:** `FASTLY_API_TOKEN`.
- **CoinGecko / CMC:** `COINGECKO_API_KEY`, etc.

Keep `.env` out of version control and restrict access to the file (e.g. `chmod 600 .env`).

---

**Refs:** `.env.example` (root) | [SCRIPT_ENV_VARS_REFERENCE](../11-references/SCRIPT_ENV_VARS_REFERENCE.md) | [MASTER_SECRETS_INVENTORY](MASTER_SECRETS_INVENTORY.md)