99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# 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.
|