Homelab-manager/INTEGRATIONS.md

# Integration & DNS provider access requirements

What credential to create in each target system, and the minimum
access it needs, when adding an integration or DNS provider in
Homelab Manager (Integrations → Add integration, or DNS → Add
provider). All credentials are entered in-app and encrypted at rest —
nothing is read from environment variables.

Every adapter listed here performs write actions (starting/stopping
things, editing DNS records, etc.), not just reads — a read-only
credential will fail as soon as you use one of those actions, even if
the dashboard views themselves load fine.

## Integrations

### Tailscale

- **Config fields:** Tailnet, API key
- **Auth:** Bearer token against `api.tailscale.com`
- **Actions used:** list devices, remove a device, authorize/deauthorize a device
- **Required access:** An API access token (or OAuth client) with **Devices Core: Read + Write** — create one under the admin console → Settings → Keys. Read-only isn't enough since remove/authorize are write calls.

### Proxmox VE

- **Config fields:** Proxmox URL, API token ID, API token secret, allow self-signed certificate
- **Auth:** `PVEAPIToken=<tokenId>=<tokenSecret>` header
- **Actions used:** list nodes/VMs/LXCs, read guest config and live status, read node host stats and storage usage, start/stop/reboot/shutdown a guest
- **Required access:** A dedicated API token (Datacenter → Permissions → API Tokens) with a role granting **VM.Audit + VM.PowerMgmt** (e.g. `PVEVMAdmin`) on the VMs/LXCs to manage, **plus Sys.Audit and Datastore.Audit** on the node(s) for the host CPU/RAM/storage cards to populate. A token scoped to VM management only will still work for the guest list and power actions — it'll just show an error on the per-node hardware card instead of failing outright.
- **Notes:** self-signed certificates are supported via the "Allow self-signed certificate" checkbox — common for an internal PVE host.

### Synology DSM

- **Config fields:** Synology DSM URL, Username, Password, allow self-signed certificate
- **Auth:** DSM session login (`SYNO.API.Auth`), session id reused until it expires
- **Actions used:** read-only — storage/volume/disk health, system info, network info. No writes.
- **Required access:** A DSM user account that can view **Storage Manager** and **System Information** (a regular admin-group account is simplest; a dedicated read-only user works too since nothing is ever changed). **2FA/OTP on the account is not supported** — use an account without it enabled, or DSM's application-specific password if your setup requires 2FA elsewhere.
- **Notes:** works over plain HTTP or HTTPS depending on the URL you enter; self-signed certs supported.

### Semaphore (Ansible Semaphore / Semaphore UI)

- **Config fields:** Semaphore URL, API token
- **Auth:** Bearer token
- **Actions used:** list projects, list templates, run a template (creates a task)
- **Required access:** A user API token with access to every project you want visible, and **permission to run templates** in those projects — a viewer/guest-level project role can list templates but will fail on "Run", so the account needs at least the operator-equivalent role Semaphore's own project permissions define.

### Gitea

- **Config fields:** Gitea URL, API token
- **Auth:** `Authorization: token <token>` header
- **Actions used:** list repos, list Actions workflow runs, re-run failed jobs in a run
- **Required access:** A personal access token with **`repo`** scope (read access to repos, including private ones you want tracked) and Actions read/write — generate it under the account → Settings → Applications → Generate New Token, with the `repository` and `write:repository`/Actions permission groups enabled (exact grouping depends on your Gitea version's token scope UI). Read-only Actions access isn't enough since re-running jobs is a write call.

### Dockhand

- **Config fields:** Dockhand URL, API token
- **Auth:** Bearer token against Dockhand's own API
- **Actions used:** list environments/containers, check for image updates, start/stop/restart a container
- **Required access:** A Dockhand API token belonging to a user with access to every environment (Docker host) you want visible, with permission to **start/stop/restart containers and trigger update checks** in each — not just view them.

## DNS providers

### Cloudflare

- **Config fields:** API Token
- **Auth:** Bearer token against the Cloudflare v4 API
- **Actions used:** list zones, list/create/update/delete DNS records
- **Required access:** A scoped API token (My Profile → API Tokens → Create Token) with **Zone → Zone → Read** and **Zone → DNS → Edit**, restricted to the zone(s) you want managed. `DNS Read` alone isn't enough — record add/update/delete need `Edit`.

### Loopia

- **Config fields:** Username, Password
- **Auth:** Full account credentials sent on every XML-RPC call — Loopia's API has no scoped API-key concept
- **Actions used:** list domains/subdomains/zone records, add/remove zone records and subdomains
- **Required access:** The full Loopia account username and password. There's no way to scope this down at the API level — the credential has the same access as logging into the Loopia customer portal.

### Pi-hole

- **Config fields:** Pi-hole URL, Web password
- **Auth:** Session login against the Pi-hole v6 API (`/api/auth`) using the admin web password, session id cached until it expires
- **Actions used:** read/add/update/delete local DNS "hosts" (A/AAAA) and CNAME records
- **Required access:** The Pi-hole admin web interface password — Pi-hole v6 doesn't have per-feature roles, so this is effectively full admin access to that Pi-hole instance.

### Azure DNS

- **Config fields:** Tenant ID, Client (application) ID, Client secret, Subscription ID
- **Auth:** OAuth2 client-credentials (Azure AD app registration / service principal), then Bearer token against Azure Resource Manager
- **Actions used:** list DNS zones, list/read/create/update/delete record sets
- **Required access:** The service principal needs the **DNS Zone Contributor** role (or higher) on the subscription or resource group containing the DNS zone(s) — assign it under Azure Portal → the zone or resource group → Access control (IAM) → Add role assignment.

### cPanel

- **Config fields:** cPanel URL, Username, API Token, allow self-signed certificate
- **Auth:** `Authorization: cpanel <username>:<apiToken>` header (UAPI for reads, API 2 for record writes)
- **Actions used:** list zones/domains, read a zone's records, add/remove a zone record
- **Required access:** An API token generated under cPanel → Security → Manage API Tokens for the account that **owns** the domain(s) being managed. cPanel tokens inherit the full account's permissions — there's no separate DNS-only scope to grant.

### Technitium DNS Server

- **Config fields:** Technitium URL, API Token
- **Auth:** Bearer token
- **Actions used:** list zones, read zone records, add/delete records (an "update" is implemented as delete + add)
- **Required access:** A token tied to a Technitium user account with **Zones: View + Modify** permission — view-only will fail on record changes since updates are add/delete calls under the hood.