auth.your-domain.com

State machine

Each domain on the app's Domains tab moves through:

• pending — added; waiting for the TXT record.
• verifying — a DNS check is running.
• verified — ownership proven; the certificate is being issued.
• active — the certificate is live and the domain serves your branded login page.
• failed — the TXT record wasn't visible within 24 hours of adding the domain, or the certificate wasn't issued within 24 hours of verification. Publish what's missing, then click Verify again.

When a check fails, the reason shows on the domain in the dashboard. Pending and verified domains are also checked in the background every 6 hours, so a domain can go live without anyone clicking.

Setup, step by step

1. In the per-app Domains tab, click + Add domain and paste auth.your-domain.com. The dashboard shows the records to publish.
2. Add a TXT record at _tillauth.auth.your-domain.com with the verification token as its value.
3. Add a CNAME on auth.your-domain.com pointing at the target the dashboard shows. Apex domains aren't supported; use a subdomain.
4. Click Verify now. Once the TXT record is visible the domain moves to verified and certificate issuance starts. If the certificate needs its own validation records, they appear under the others.
5. Click Check certificate until the domain turns active. The hosted-login page now serves on your domain.

What runs on your domain

• The hosted-login pages — sign-in, sign-up, magic links, MFA, passkeys and password reset, branded with the app's Branding settings.
• The app's key set at https://auth.your-domain.com/.well-known/jwks.json. It holds only this app's keys once the app signs with its own (the shared keys too while it doesn't). Tokens still name the TillAuth issuer, so keep checking iss and app; @tillstack/auth-node does both with its defaults.
• Google, GitHub and OIDC callbacks stay on TillAuth at https://auth.tilldev.dev/v1/oauth/<provider>/callback, so the redirect URI registered with your provider doesn't change when you add a domain.

Health checks

Every 6 hours each live domain is checked: the hostname still resolves to the target the dashboard shows, and its certificate is valid and renewing. The Domains tab shows the result, the certificate's expiry and the time of the last check; Check now runs one on demand.

• Needs attention — a renewal is in progress, needs records you haven't published yet (they appear on the domain), or is overdue with 21 days or less left.
• Failing — the hostname doesn't resolve or points somewhere else, the certificate lapsed or its renewal timed out (it's restarted automatically), or the certificate expires within 7 days.

Owners and admins get one email and a notification in the dashboard when a domain has failed or needed attention for two checks in a row, or at once when its certificate expires within 7 days. The next alert comes only after the domain has recovered. A setup that stalls into failed sends one too. From the terminal: tilldev auth domains <app> check <hostname>.

Cert lifecycle

• Issued and renewed automatically. You don't upload anything.
• Someone who takes over your DNS can point the hostname at their own server, and no certificate setting on our side prevents that. What they can't do is sign tokens: those need the app's signing key, which never leaves TillAuth, so a verifier that checks signatures refuses anything a copied login page hands out.

Removing a custom domain

Removing a domain on the Domains tab releases its certificate and stops serving on it. The <slug>.tilldev.app URL keeps working. Active sessions are not invalidated — tokens are app-scoped, not domain-scoped.

Limits

• An app can have more than one domain; each hostname belongs to one app.
• Apex domains aren't supported — use auth., login., or another subdomain.
• Certificate issuance usually takes seconds to minutes after ownership is verified.