Custom domains

One DNS verification covers every web app in the Workspace. After the domain is verified, you add the addresses you want under it, and Tokay issues and renews their HTTPS certificates automatically.

Last updated

AI agent? Start with llms.txt.

Verify the domain once for the Workspace

One verification covers every web app in the Workspace, so you do not repeat DNS setup for each Service.

  1. Open Domains under Workspace, then choose Add domain.
  2. Enter the domain you want to use, such as yourcompany.com or internal.yourcompany.com.
  3. Add the records Tokay shows wherever your DNS is managed. Tokay finds which company hosts your DNS, names it, and shows each record the way that company's form asks for it.
    • A TXT record named _tokay-verification with the value Tokay shows. It proves the domain is yours, and it is the only record verification needs.
    • Optionally, a CNAME named * that sends every address you add later to your Workspace's address, such as aa1b2c3d.ingress.tokay.app. Without it, each address you add shows the one record it needs.
  4. Tokay checks the TXT record every few minutes. Choose Check now to check right away. Each check shows what Tokay found, such as a record that is not there yet or a value that does not match.

The DNS records belong in the dashboard for the provider that hosts your domain, such as Cloudflare, GoDaddy, or Namecheap. When Tokay recognizes the provider, it links to that dashboard. DNS changes can take a while to appear everywhere, so a record you just added may need a few minutes.

If Cloudflare hosts your DNS, set the records for your Tokay addresses to DNS only, the grey cloud. While Cloudflare proxies a record, Tokay can't set up HTTPS for the address.

A domain that is not verified within 7 days is removed, so its name is free to add again later.

Adding DNS records for the first time

DNS records live with the company that sold you the domain or hosts it, such as Cloudflare, GoDaddy, or Namecheap. Sign in there, open the domain, and look for a page called DNS records, DNS management, or Manage DNS.

Every provider's form asks for the same three things. Type is the kind of record, TXT, CNAME, or A. Name, which some providers call Host, is the address the record answers for. Value, also called Target, Content, or Points to, is what the record says. Copy each part from Tokay into the matching box and leave TTL on its default.

Most forms fill in your domain for you, so the Name box takes only the part in front of it. Once Tokay knows where your DNS is hosted, it shows names that way, with @ for the domain itself. Until then it shows the full name, such as _tokay-verification.yourcompany.com. If the form already ends in yourcompany.com, enter only _tokay-verification.

A record you save can take a few minutes to reach the rest of the internet, and sometimes longer. Leave the page and come back whenever you like. Tokay checks every few minutes and shows what it found under the domain. If Tokay reports a TXT record with a different value, the record exists but its value was mistyped or an old one is still there. Correct it and Tokay picks it up on the next check.

HTTPS for every address

Each address you add under the domain gets its own HTTPS certificate. Tokay requests it from Let's Encrypt and serves the address once its certificate is ready, usually within minutes. Until then the address shows the DNS record it still needs, or what to fix in DNS when Let's Encrypt cannot reach it through Tokay. Certificates renew automatically well before they expire.

The domain itself, such as yourcompany.com, can't take a CNAME, because DNS allows none there. When you give a Service that address, Tokay shows the record your DNS provider takes instead. That's an ALIAS or ANAME record at most providers, a CNAME at providers that flatten it, such as Cloudflare, and an A record at providers that offer neither, such as GoDaddy. An ALIAS keeps working if Tokay moves your Workspace, so Tokay suggests it wherever your provider offers one.

After you fix a DNS record, choose Check again on the address so Tokay looks now instead of at its next retry. Let's Encrypt limits how often one name may fail, so each address can be checked again every 15 minutes, and a Workspace can check 10 addresses an hour.

Let's Encrypt issues at most about 50 new certificates per registered domain each week, so a Workspace can add about 50 new custom addresses a week under one domain.

Choose the right address for each use

You can give people a short address without making scripts or integrations depend on a name you may move later.

Every web app keeps its Tokay address, such as myservice-r4k7x2m9.tokay.app. Renaming the Service keeps the old address redirecting, so use it for automation and integrations.

A custom URL is a name you choose under the Service's Service URLs, such as dashboard.yourcompany.com. Custom URLs are meant for people and can move from one Service to another. Use them in links people open, not in automation.

The apex domain, such as yourcompany.com, is assigned explicitly to one Service. Tokay does not route it automatically.

Webhooks keep their Tokay addresses

Webhook integrations keep the stable address Tokay assigned to them. Custom domains apply to web apps, while webhook URLs continue to use their tokay.app addresses.

Removing a domain leaves the apps online

You can disconnect a custom domain without taking the apps themselves offline. Removing a verified domain immediately removes every custom URL under it, but each app is still available at its tokay.app address.