# Set DNS with united-domains

Connect a united-domains API key once. MainPath writes A and CNAME records into your zone.

> Source: https://www.mainpath.ai/en/docs/dns-united-domains/

If your domain lives at [united-domains](https://www.united-domains.de/), you no longer have to copy records by hand. You store an API key under **Connections**; once a project has domains, MainPath writes the records into the matching zone.

Manual DNS is still possible. See [Configure a DNS record]({{< relref "domain-how-to" >}}).

## API key at united-domains

This uses the **united-domains DNS API** (`dnsapi.united-domains.de`), the same API model as IONOS Hosting DNS. The domain reselling API and keys from IONOS Cloud will not work here.

1. Sign in to your united-domains account.
2. Book the [DNS API](https://www.united-domains.de/domain-dnsapi/) product for the portfolio if it is not active yet.
3. Open [Getting started with the APIs](https://www.united-domains.de/help/faq-article/erste-schritte-mit-den-united-domains-apis/) and create an API key.
4. Copy the **public prefix** and **secret**. In MainPath you enter them as a **single** line `prefix.secret` (joined with a dot). Do not paste them with a space or a line break.

Without the DNS API product booked, united-domains rejects the key. The API covers every domain in the portfolio whose nameservers point to united-domains (`ns.udag.de`, `ns.udag.net`, `ns.udag.org`).

## Connection in MainPath

1. Open **Connections** and **Add connection**.
2. Under **DNS**, choose the **united-domains** tile.
3. Paste the API key and save. MainPath checks whether the key is valid and which zones it can see.

Several united-domains connections in one organization are allowed. If a hostname matches more than one zone, MainPath uses the most specific one (`shop.example.com` before `example.com`).

## What is written

MainPath uses the same hosts you see under **Domains**.

- Records are only written when a real server address already exists.
- Existing records of the same type are updated; the whole zone is never replaced.
- Changes usually show up quickly.

```mermaid
flowchart LR
  org["united-domains connection"]
  domains["Domains in MainPath"]
  zone["united-domains zone"]
  server["Your server"]
  org --> zone
  domains -->|"A / CNAME"| zone
  zone --> server
```

After you save a project, MainPath tries to align missing or mismatched records. You can see the check status in the domain overview.

## SSL via DNS-01 (optional)

If Let's Encrypt cannot reach the server (no public HTTP/443, firewall, internal IP), open this connection's details and tick the affected domains. MainPath then writes the `_acme-challenge` TXT record into this zone. Unticked domains keep the existing TLS-ALPN challenge on the server.

## Troubleshooting

- **Invalid key**: Check the `prefix.secret` format (one dot, no spaces), book the DNS API in the portfolio, and update the connection.
- **No record at united-domains**: The domain is not in a zone this key can see. Check the account or zone name.
- **Zone visible, domain unreachable**: The zone exists, but the domain's nameservers point elsewhere. MainPath flags this in the connection details and on Domains. Point the nameservers at the registrar to `ns.udag.de`, `ns.udag.net`, and `ns.udag.org`.
- **Status in MainPath still red**: DNS often takes a few minutes, or the server does not have a known address yet.

## See also

- [Domain setup]({{< relref "domain" >}})
- [Configure a DNS record]({{< relref "domain-how-to" >}})
- [Connections]({{< relref "connections" >}})
- [Set DNS with IONOS]({{< relref "dns-ionos" >}})
- [Set DNS with Cloudflare]({{< relref "dns-cloudflare" >}})