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.deandstrasse.deare 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 theidncommand 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_DOMAINon 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
NXDOMAINfor 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.