# Set DNS with IONOS

Connect an IONOS API key once. MainPath writes A and CNAME records into your zone.

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

If your domain lives at [IONOS](https://www.ionos.com/), 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 in IONOS

This uses the **Hosting DNS API** (`api.hosting.ionos.com`), not IONOS Cloud and not the Data Center Designer. A Cloud token from the DCD will not work here.

1. Sign in to your IONOS account (customer number, email, or domain).
2. Open the [Developer Hub](https://developer.hosting.ionos.com/docs/getstarted) and enable **API access** once (accept the terms).
3. Under [API Keys](https://developer.hosting.ionos.com/keys) create a new key.
4. Copy the **public prefix** and **secret**. In MainPath you enter them as a **single** line `prefix.secret` (joined with a dot). IONOS often shows the two parts separately; do not paste them with a space or a line break.

Without API access enabled on the account, IONOS rejects the key even when prefix and secret look correct.

## Connection in MainPath

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

Several IONOS 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["IONOS connection"]
  domains["Domains in MainPath"]
  zone["IONOS 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), enable API access in the IONOS account, and update the connection. A token from IONOS Cloud / DCD is the wrong type.
- **No record in IONOS**: The domain is not in a zone this key can see. Check the account or zone name.
- **Zone visible, domain unreachable**: The zone exists at IONOS, but the domain's nameservers point elsewhere. MainPath flags this in the IONOS details and on Domains. Point the nameservers at the registrar to IONOS (`ns*.ui-dns.*`).
- **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 Cloudflare]({{< relref "dns-cloudflare" >}})
- [Set DNS with united-domains]({{< relref "dns-united-domains" >}})
- [Set DNS with GoDaddy]({{< relref "dns-godaddy" >}})
- [Set DNS with Hetzner]({{< relref "dns-hetzner" >}})
- [Set DNS with Hostinger]({{< relref "dns-hostinger" >}})
- [Set DNS with DigitalOcean]({{< relref "dns-digitalocean" >}})
- [Set DNS with Gandi]({{< relref "dns-gandi" >}})