Custom domains

One DNS verification covers every web app in the Workspace. After the domain is verified, Tokay creates the custom app addresses and 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 shown by Tokay wherever your DNS is managed:
    • a TXT record at _tokay-verification.yourcompany.com with the value Tokay shows. It proves the domain is yours.
    • a CNAME that sends *.yourcompany.com to ingress.tokay.app, so traffic for your app addresses reaches Tokay.
    • for the apex domain itself, such as yourcompany.com, an A record to the address Tokay shows. Tokay keeps that address fixed, so the record works at every DNS provider. Do not add a CNAME at the apex.
  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. DNS changes can take a while to appear everywhere, so a record you just added may need a few minutes.

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.

Some providers fill in your domain for you, so the Name box takes only the part in front of it. If Tokay shows _tokay-verification.yourcompany.com and the form already ends in yourcompany.com, enter _tokay-verification. If the form accepts the full name, enter the full name.

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

After verification, every web app in the Workspace gets an address under the domain. Tokay requests an HTTPS certificate for each address from Let's Encrypt and serves the address once its certificate is ready, usually within minutes. Until then the address shows as setting up. Certificates renew automatically well before they expire.

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.

Tokay gives each web app an address such as myservice-r4k7x2m9.yourcompany.com. That address is stable unless the Service is recreated. 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 address and custom URL under it, but each app is still available at its tokay.app address.