developers.acme.com, instead of Unkey’s portal host. You attach the domain to a portal, publish two DNS records, and Unkey verifies them, routes the hostname to your portal, and issues a certificate for it.
Before you start
A portal domain follows the same naming rules as a Compute custom domain.- Each name can be attached once in your workspace, to one portal or one environment, not both.
- The name must be under a registrable domain.
developers.acme.co.ukworks, butco.ukon its own doesn’t. Wildcards and IP addresses aren’t allowed. - A workspace can hold up to 10 portal domains.
- Port 80 must reach Unkey as well as 443, so Let’s Encrypt can check the name before issuing a certificate.
Attach a domain
Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. See Permission reference for every permission.
Permission on the portal itself doesn’t cover its domains. Without the permission, the request fails with 404, or with 403 naming the missing permission if your root key can read the portal.
Add the domain
Call The response has the domain’s
portal.createDomain with the portal’s ID or slug and the hostname:pdom_ ID and the dnsRecords to publish. If your DNS provider supports Domain Connect, it also has domainConnect.url, a link that creates the records at your provider in one step. portal.getDomain returns the same link.Publish the DNS records
Create both records at your DNS provider, exactly as
dnsRecords lists them, with a TTL of 60 seconds:ALIAS means whatever your provider calls an alias at the apex: ALIAS, ANAME, or a flattened CNAME. If your provider proxies traffic, create the routing record as DNS-only.Wait for verification
Unkey checks DNS about once a minute for up to 24 hours. Poll
portal.getDomain with the portal and the domainId to follow it. The status goes from pending to verifying to verified, and each record has a verified flag showing whether Unkey has found it.Once the domain is verified, it serves your portal, and Unkey requests a Let’s Encrypt certificate for it under your workspace. Certificates renew automatically.portal.listDomains returns every domain on a portal, verified or not.
Send users to your domain
portal.createSession returns a URL on Unkey’s portal host. To keep users on your domain, replace the host in that URL with your domain before you redirect them. The rest of the URL, including the one-time code, stays the same. See Portal sessions.
Verification failed
After 24 hours without the right records, the status becomesfailed and verificationError says why. Fix the records, then call portal.verifyDomain to start a new 24 hour window. Calling it on a domain that’s already verified succeeds and does nothing.
Things to check:
- Publish both records, even for a subdomain. A subdomain can pass with the CNAME alone, but an apex domain or a record your provider proxies or flattens can only pass with the TXT record.
- Copy values exactly. Unkey compares them character for character.
Move a domain from another workspace
If another workspace has already verified the name, publish the TXT record. When your verification passes, the domain moves to your workspace, and the other workspace’s claim is markedfailed.
Remove a domain
Callportal.deleteDomain with the portal and the domainId. A verified domain stops serving your portal right away. The certificate isn’t revoked, and you remove the DNS records yourself.
Deleting a portal with portal.deletePortal removes its domains the same way.
Adding, verifying, and removing a domain write portal.domain.create, portal.domain.verify, and portal.domain.delete audit log entries.