> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tieback.io/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tieback.io/docs/_mcp/server.

# Custom Hostname Lifecycle

> States and transitions of a tieback custom hostname, from initial request through DNS verification, certificate issuance, live traffic, and removal.

A custom hostname (for example, `passport.brand.com`) progresses through a defined lifecycle inside **tie*back***. This page documents the states and what they mean operationally.

## Lifecycle States

| State                    | Meaning                                                                              | Next action                                            |
| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| **Requested**            | The brand has registered the hostname in the workspace; DNS records have been issued | Add the displayed CNAME / TXT records to your DNS      |
| **Pending Verification** | DNS records are being polled                                                         | Wait: typically minutes to hours                       |
| **Verified**             | Hostname ownership is confirmed                                                      | Certificate issuance begins automatically              |
| **Certificate Issued**   | TLS certificate is provisioned and active                                            | Hostname is live for resolver traffic                  |
| **Active**               | Live and serving passport traffic                                                    | None: operational                                      |
| **Failing**              | Periodic re-validation has failed                                                    | Re-check DNS; the dashboard surfaces the failing check |
| **Removed**              | The brand has removed the hostname                                                   | Custom URLs revert to the default subdomain            |

## What Resolves Where

* The **dashboard** is always served from the platform subdomain; custom hostnames do not expose the dashboard
* The **resolver** serves passport traffic at both the platform subdomain and any verified custom hostname
* Non-resolver app paths on a custom hostname return **403 Forbidden** by design; see the custom domain restrictions policy

## Re-Validation

Verified hostnames are periodically re-validated. If DNS or certificate health degrades, the hostname transitions to **Failing** and the workspace receives a notification. Resolver traffic continues to serve from the platform subdomain so passports remain reachable.

## Removal

Removing a custom hostname is immediate. Subsequent traffic to the removed hostname stops resolving via **tie*back***. Existing passport URLs minted under that hostname continue to function only if DNS is repointed back; otherwise consumers should be migrated to the platform subdomain URL.

## Related Docs

* [Domain Architecture](/domains-custom-hostnames/domain-architecture)
* [Custom Hostname Setup](/domains-custom-hostnames/custom-hostname-setup)
* [DNS Setup Guide](/domains-custom-hostnames/dns-setup-guide)
* [Troubleshooting](/domains-custom-hostnames/troubleshooting)