AdGuard Home
AdGuard Home API credentials setup: expose AdGuard Home's administrator API through restricted HTTPS and use an existing web username and password to manage DNS rewrites.
On this page
AdGuard Home API credentials permissions
- Credential type
- Web interface login
- Preview access
- HTTP Basic access to status and the DNS rewrite list
- Apply access
- HTTP Basic access to add, update, and delete DNS rewrites
- API endpoint
- You provide a public API endpoint.
Additional access
DNSControl id
{
"TYPE": "ADGUARDHOME"
}Create credentials
Expose AdGuard Home's administrator API through restricted HTTPS and use an existing web username and password to manage DNS rewrites.
Access you'll grant
HTTP Basic access to status and the DNS rewrite list
HTTP Basic access to add, update, and delete DNS rewrites
Before you start
- Administrator access to AdGuard Home and the cleartext password for a configured web user.
- A public hostname, a publicly trusted TLS certificate, and a firewall or reverse proxy that can allow-list our egress IP.
Setup steps
0 of 5 done
Confirm an authenticated web user
Sign in to the AdGuard Home web interface with the account you will use. The API uses the same administrator username and password with HTTP Basic authentication;
users: []disables authentication and is not suitable for a public endpoint.Relevant configuration keysusers: - name: dnsmigrator password: <bcrypt-hash>Enable HTTPS
Open Settings → Encryption settings, enable encryption, and fill Server name, Certificates, and Private key, then select Save settings. Alternatively, terminate TLS at a reverse proxy. The certificate must chain to a public trust root.
AdGuardHome.yaml TLS keystls: enabled: true server_name: adguard.example.com port_https: 443 certificate_path: /path/to/fullchain.pem private_key_path: /path/to/privkey.pemRestrict the public endpoint
Allow only
our egress IPat the firewall or reverse proxy. DNSMigrator calls this endpoint from its servers over the public Internet. Its SSRF guard rejects private, loopback, link-local, CGNAT, metadata, documentation/reserved, and other non-public addresses; it checks every DNS answer and pins one validated IP for the connection. Do not expose an unrestricted administrator UI to the Internet.Enter the URL and login
Enter the public origin in AdGuard Home URL; either the origin or a URL ending in
/controlis accepted. Paste the same Username and cleartext Password used by the web interface. Do not paste the bcrypt hash from the configuration file.URL formathttps://adguard.example.comAdd optional grouping domains
AdGuard Home has DNS rewrites, not authoritative zones. In Domains, list suffixes such as
home.example.comwhen rewrites should be grouped predictably; otherwise DNSMigrator guesses from the final two labels. Check access, then review the imported rewrite groups.Domain hintshome.example.com, example.org
Troubleshooting
401 Unauthorized
Use the web-interface username and cleartext password. Confirm users is not empty and that the reverse proxy forwards the Authorization header.
The endpoint is blocked or its certificate is rejected
Use public HTTPS with a complete trusted chain and a hostname whose every DNS answer is public. Private, split-horizon, CGNAT, and reserved addresses are refused.
Records appear under the wrong domain
Enter the intended suffixes in Domains. AdGuard Home has no native zones, so this field only controls grouping.
The check passes but rewrite changes fail
The check reads only /control/status. Verify that the proxy permits GET, PUT, POST, and DELETE under /control/rewrite and inspect AdGuard Home logs.
Official documentation
- AdGuard Home: configuration
- AdGuard Home: configure encryption
- AdGuard Home: OpenAPI
- DNSControl: AdGuard Home provider
Guide checked against the official documentation on .
Credential fields
| Field | Requirement | Where to find it |
|---|---|---|
| AdGuard Home URLurl | Required | Public HTTPS origin of the AdGuard Home UI/API. A trailing /control is removed automatically. |
| Usernameusername | Required | A configured AdGuard Home web-interface user name from users[].name. |
| Passwordpassword | Required | The user's cleartext web password. Do not enter the bcrypt value stored in users[].password. |
| Domainszones | Optional | Optional comma- or whitespace-separated suffixes used only to group flat DNS rewrites into migration zones. |
Capabilities
- Create zones
- No
- List zones
- Yes
- DNSSEC
- Not available through this connection
- Minimum TTL
- 300 seconds
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
- ALIAS
AdGuard Home-only types
- ADGUARDHOME_A_PASSTHROUGH
- ADGUARDHOME_AAAA_PASSTHROUGH
These records need translation or review when you move to another provider.
Caveats
- AdGuard Home usually runs on a private network; we refuse private addresses by design, so it is only reachable if you expose its web interface publicly over HTTPS.
- Only DNS rewrites are managed: A, AAAA, CNAME (ALIAS at the apex) and the A/AAAA passthrough rules. Rewrites have no per-record TTL (the server uses one global TTL), so we report 300 seconds as DNSControl does.
- AdGuard Home has no zones. We group rewrites by the domains you list, or by the last two labels of each name.
Troubleshooting
- 401 Unauthorized
- Use the web-interface username and cleartext password. Confirm users is not empty and that the reverse proxy forwards the Authorization header.
- The endpoint is blocked or its certificate is rejected
- Use public HTTPS with a complete trusted chain and a hostname whose every DNS answer is public. Private, split-horizon, CGNAT, and reserved addresses are refused.
- Records appear under the wrong domain
- Enter the intended suffixes in Domains. AdGuard Home has no native zones, so this field only controls grouping.
- The check passes but rewrite changes fail
- The check reads only /control/status. Verify that the proxy permits GET, PUT, POST, and DELETE under /control/rewrite and inspect AdGuard Home logs.