Internationalised Domain Names (IDN)

Domain names with letters outside ASCII (zażółć.pl, тест.рф, münchen.de) travel through DNS as punycode: xn--za-6ja4f8n1l.pl. PrimeDNS accepts both forms everywhere, stores and serves the punycode form, and shows you the form you typed. This guide explains what to expect and how look-alike names are handled.

1. Adding a zone

Enter the name in Unicode or in punycode, in any letter case. Both give the same zone, so a second attempt with the other form answers 409 DOMAIN_EXISTS instead of creating a duplicate.

curl -X POST https://api.primedns.net/v1/domains/external \
  -H "Authorization: Bearer $PRIMEDNS_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "zażółć.pl"}'

The response carries both names:

{ "domain": "xn--za-6ja4f8n1l.pl", "unicode_name": "zażółć.pl", "homograph_risk": false, ... }

domain is the name DNS uses. unicode_name is for display. Use whichever your tooling expects: the API accepts either in paths such as /v1/zones/{zone}/export.

2. Records

  • Record names may use Unicode labels (żółw, *.żółw); they are stored as punycode.
  • Names inside record content (CNAME, MX, NS, SRV, PTR, DNAME, ALIAS targets) are converted the same way. TXT content is stored exactly as you typed it.
  • The panel shows names in Unicode in lists, record editors and the audit log. The data behind a form field (what is sent when you save) stays punycode.
  • The conversion follows IDNA2008 behaviour for ß and final ς: straße.de and strasse.de are two different names.

3. Certificates

For DNS-01 challenges the challenge record is created under the punycode name, whichever form the client sends. Practical advice:

  • Give your ACME client the punycode name (-d xn--za-6ja4f8n1l.pl). It is the safe choice because it needs no extra tooling.
  • acme.sh also accepts -d zażółć.pl, but needs the idn command installed and refuses to run without it. That check is in acme.sh, before anything reaches PrimeDNS.
  • An API key limited to acme:name:... can be created with either form; it is stored as punycode.

4. Look-alike names (homographs)

Some letters from different alphabets look identical: the Cyrillic а and the Latin a make аpple.com look like apple.com. PrimeDNS treats a name as a homograph risk when a label:

  • mixes alphabets in a way ICU's spoof checker flags (for example Latin letters next to Cyrillic or Greek ones),
  • contains symbols or emoji,
  • contains invisible or formatting characters (zero-width space, bidi controls), or a combining mark with nothing to attach to.

A label written entirely in one alphabet, such as тест.рф or αβγ.gr, is not flagged.

What happens with a flagged name:

  • Adding a zone for a domain you own: allowed. The zone is created with "homograph_risk": true, the panel shows a warning, and displays the name in its punycode form everywhere, so nobody reading the panel is misled.
  • Registering a domain: refused with 422 HOMOGRAPH_RISK, before any payment.
  • Mail and alerts: a name is shown as zażółć.pl (xn--za-6ja4f8n1l.pl); a flagged name is shown in punycode only.

The check is a heuristic, not a guarantee. It does not judge a whole label written in one alphabet that merely resembles another alphabet, because that would block genuine domains in Cyrillic and Greek. When a name matters (a brand, a payment page), compare the punycode form, which cannot hide a different letter.

Troubleshooting

  • 422 INVALID_DOMAIN on a name that looks fine: a label over 63 octets once converted to punycode, a character IDNA does not allow, or invalid punycode. The conversion of a long Unicode label can exceed 63 octets even if it has fewer than 63 characters.
  • A new zone does not answer yet: the name servers can answer NXDOMAIN for the first minute or so after a zone is created. Retry before concluding that something is wrong.
  • A name appears in punycode in the panel: it was flagged as a homograph risk, or it could not be converted to Unicode. Both are intentional.