> 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 Setup

> How to connect your own domain to tieback so consumers scan and view Digital Product Passports on your branded hostname, with DNS and activation steps.

tieback supports custom hostnames for Digital Product Passports. This allows consumers to scan QR codes and view passports on your own branded domain, such as `passport.yourbrand.com`.

## Prerequisites

1. Your platform subdomain must be configured and active (e.g. `yourbrand.tieback.io`)
2. You must have **Owner** or **Admin** access to the workspace

## Setting Up a Custom Hostname

### Step 1: Add Your Domain

Navigate to **Settings → Domains** and enter your custom hostname in the custom domain field.

**Requirements:**

* Must be a subdomain (e.g. `passport.yourbrand.com`), not an apex/root domain
* Only lowercase letters, numbers, hyphens, and dots are allowed
* Internationalized domain names (IDN) are not supported in v1

### Step 2: Configure DNS

After adding your domain, you'll see DNS configuration instructions:

| Record Type | Name/Host  | Target/Value           | TTL  |
| ----------- | ---------- | ---------------------- | ---- |
| CNAME       | `passport` | `yourbrand.tieback.io` | Auto |

Add this CNAME record at your DNS provider. The name should match the subdomain portion of your custom hostname (e.g. `passport` for `passport.yourbrand.com`).

> **Warning**
>
> The CNAME target must be your brand's platform subdomain (`yourbrand.tieback.io`), not
> `tieback.io` or `app.tieback.io`.

### Step 3: Wait for Activation

After DNS propagation:

1. Click **Refresh Status** in the Domains settings
2. The status will progress through:
   * **Pending DNS**: waiting for your DNS CNAME to propagate. This typically takes minutes but can take up to 24–48 hours depending on your DNS provider.
   * **Activating**: DNS verified, SSL certificate being provisioned. This usually completes within 15 minutes.
   * **Active**: custom hostname is live and serving traffic.

If activation has not completed after 48 hours, contact support.

## Supported Paths

Custom hostnames support **public consumer paths** only:

| Path                               | Supported | Purpose                                           |
| ---------------------------------- | --------- | ------------------------------------------------- |
| `/01/*`, `/mu/*`, `/mb/*`, `/ml/*` | ✅ Yes     | Resolver paths: QR code scan entry points         |
| `/p/*`                             | ✅ Yes     | Public passport page rendering                    |
| `/dashboard`, `/settings`, etc.    | ❌ No      | Use the platform subdomain for application access |

## Changing Your Custom Hostname

To change to a different custom domain:

1. Enter the new hostname in the domain field
2. Click **Change domain**
3. The old hostname will be removed automatically
4. Configure DNS for the new hostname

Your platform subdomain remains available as a fallback throughout any domain changes.

## Removing a Custom Hostname

Click **Remove domain** to remove the custom hostname. Your platform subdomain (`yourbrand.tieback.io`) will continue to work.

## Troubleshooting

### Status shows "Pending DNS"

* Verify the CNAME record is correctly configured at your DNS provider
* DNS changes typically propagate within an hour but can take up to 24–48 hours
* Click **Refresh Status** to check again

### Status shows "Failed"

* Check that no conflicting DNS records exist for the hostname
* Ensure the CNAME target matches your platform subdomain exactly
* Try removing and re-adding the domain

### Domain shows "Manual (legacy)"

This domain was configured before automated lifecycle management was available. Remove it and re-add it through the automated flow, or contact support for assistance.

## Platform Subdomain

Your platform subdomain (`yourbrand.tieback.io`) is always available:

* It serves as a fallback if your custom hostname is not yet active
* Dashboard and application access always use the platform subdomain
* Previously issued QR codes using the platform subdomain continue to work

## Related Docs

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