# 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:

```bash
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:

1. Log in to your cPanel account
2. Go to **Security → Manage API Tokens**
3. Click **Create** and give it a name, e.g. `sloth-manager`
4. 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.