API Access Requirements

This document describes the credentials and permissions needed for each DNS provider.

Cloudflare

Credential: API Token (CLOUDFLARE_API_TOKEN)

Create a token at dash.cloudflare.com → My Profile → API Tokens → Create Token.

Use the "Create Custom Token" option and grant the following permissions:

Resource	Permission
Zone — Zone	Read
Zone — DNS	Edit

Scope the token to specific zones or all zones depending on your preference. Do not use a Global API Key — a scoped token is safer.

Loopia

Credentials: API username (LOOPIA_USER) and password (LOOPIA_PASSWORD)

Create a dedicated API user at customerzone.loopia.se → My Account → API Users.

The API username will be in the format youruser@loopiaapi.

Grant access to the domains you want to manage and enable the following API method group:

Method group	Required for
DNS zone (Zone records)	List, add, update and delete DNS records

No other method groups (billing, domain registration, email, etc.) are needed.

Pi-hole

Credentials: Pi-hole URL (PIHOLE_URL) and web password (PIHOLE_PASSWORD)

The application uses the Pi-hole v6 REST API. No separate API user is needed — the same password you use to log in to the Pi-hole web interface is used here.

Set PIHOLE_URL to the base URL of your Pi-hole instance, for example http://192.168.1.x.

Note: Pi-hole local DNS only supports A, AAAA, and CNAME record types. TTL and priority are not configurable through the Pi-hole API.

Azure DNS

Credentials: Service Principal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID)

Create a Service Principal via the Azure Portal or Azure CLI:

az ad sp create-for-rbac --name "sloth-manager" --role "DNS Zone Contributor" --scopes /subscriptions/<subscription-id>

This outputs the appId (client ID), password (client secret), and tenant. Assign at minimum the DNS Zone Contributor role on the subscription or on the specific resource groups containing your DNS zones.

Credential	Description
`AZURE_TENANT_ID`	Azure AD tenant ID (shown in Azure Portal → Azure Active Directory)
`AZURE_CLIENT_ID`	Application (client) ID of the service principal
`AZURE_CLIENT_SECRET`	Client secret value
`AZURE_SUBSCRIPTION_ID`	Subscription ID (shown in Azure Portal → Subscriptions)

cPanel

Credentials: cPanel URL (CPANEL_URL), username (CPANEL_USERNAME), API token (CPANEL_API_TOKEN)

Create an API token inside cPanel:

Log in to your cPanel account
Go to Security → Manage API Tokens
Click Create and give it a name, e.g. sloth-manager
Copy the generated token

Set CPANEL_URL to your cPanel instance URL including port, e.g. https://hostname:2083.

The cPanel account must own the domains you want to manage. This adapter uses the cPanel UAPI for reading and the ZoneEdit API 2 module for writing — no WHM or root access is needed.

Self-signed certificate: If your cPanel server uses a self-signed SSL certificate, set CPANEL_INSECURE=true in .env to disable certificate verification.

Imunify360: Some hosting providers run Imunify360 WAF which blocks automated API requests. If you receive an "Access denied by Imunify360 bot-protection" error, contact your hosting provider and ask them to whitelist the IP address of the machine running the DNS Manager backend.

Adding credentials

All credentials are configured in backend/.env. Copy backend/.env.example to backend/.env and fill in the values for the providers you want to use. Providers with missing or incomplete credentials will not appear in the application.

3.8 KiB Raw Blame History