Skip to content
Avaloi

Connect a domain

Prove you own a domain with one TXT record, point it at Avaloi, and watch it go live. Covers the apex and www, names someone else holds, and what happens when you remove a domain.

Before a domain gets traffic or an HTTPS certificate, Avaloi asks you to prove you control it. The proof is one TXT record at your DNS host. It keeps anyone else from connecting a domain they do not own, and it keeps a forgotten CNAME that still points at Avaloi from being used by the wrong account.

Custom domains connect to live. Staging and multidevs use names under a domain that is already connected to live. See Domains on staging and multidevs.

Connect a domain

  1. Open your site, then Domains, and choose Add domain. Type the domain, such as example.com.

  2. The first record the dialog shows is the ownership record. It is a TXT record:

    Type Name Value
    TXT _avaloi-challenge.example.com avaloi-domain-verify= and a code

    Copy the name and the value from the dialog. Many DNS editors add your domain to the end of the name field on their own, so type only _avaloi-challenge when yours does.

  3. Add it at your DNS host. Avaloi checks every minute. The domain shows Waiting for ownership record until it resolves. Nothing is set up at Cloudflare, no certificate is ordered, and no route is made before then.

  4. When the record resolves, the dialog moves on to the usual records: the CNAME that points the domain at Avaloi and the CNAME for the server certificate. See Domains.

  5. Keep the ownership record. Avaloi checks it again every day.

The code is good for 72 hours. If it runs out, the domain shows Failed. Add the domain again to get a new code.

The apex and www

Proving example.com also proves www.example.com and any name under it, such as staging.example.com, so you add one ownership record, not one for each. It does not work the other way round: proving www.example.com does not prove example.com. When you add both in one step, Avaloi proves the apex first.

If the domain's DNS is a Cloudflare DNS zone that is active, the zone is the proof and you add no record. A zone that is still waiting for its nameservers is not.

A domain another account already uses

Two accounts cannot both hold one domain. Adding a domain someone else is about to use is allowed, because an unproven claim holds nothing. The claim that is proven first holds the name.

If you prove a domain that another account already holds, Avaloi tells you it is connected to another Avaloi account and does not say which one. Ask that account to remove it, or write to [email protected].

If the other account's ownership record has been missing for 3 days, and you can prove control now, Avaloi releases the domain to you.

If the record goes missing

Avaloi reads the ownership record every day. When it is gone, the domain keeps working and shows Ownership record missing with the date it was last seen. Add the record again and the warning clears. After 3 days without it, another account that proves control of the domain can take it.

Remove a domain

Remove it from the domain's menu. Then delete its CNAME records at your DNS host. A CNAME that still points at Avaloi does nothing for anyone else: a new account has to prove ownership first, and only you control your DNS.

Another account can connect the domain after you remove it. They get their own code, and your old record proves nothing for them.

Deleting a site or an environment removes its domains the same way. The names are free at once for you and for any other account, so you can add the domain to a new site right after you delete the old one. If a domain was left behind on a site that no longer exists, a check every 10 minutes releases it. It never touches a domain on a site that still exists. Adding the domain again asks for a new ownership record, unless an active DNS zone or a proven parent domain on your account covers it.

API

  • POST /v1/environments/{id}/domains returns the job. GET /v1/environments/{id}/domains shows ownership_proof for each domain: the method, the state (pending, expired, verified, or lapsed), and the record to add.
  • POST /v1/domains/{id}/verify checks the records now and proves the domain when the ownership record resolves.
  • GET /v1/domains/{id}/verification-records lists every record with the last check.

Refusals use these codes: hostname_in_use, hostname_taken, live_not_launched, live_domain_required, not_under_live_domain, and domain_not_proven. In MCP, add_domain, get_domain_status, and verify_domain follow the same rules.

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.