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

# DNS Setup Guide

> How to configure DNS for a tieback custom hostname, including the CNAME record, activation timings, and how to test resolver and passport responses.

This guide explains how to configure a custom hostname so your Digital Product Passports are served from your own domain.

## Overview

Instead of using the default platform subdomain (`mybrand.tieback.io`), you can configure a custom hostname like `passport.mybrand.com` to serve your Digital Product Passports.

## Prerequisites

* Access to your domain's DNS management (e.g., Cloudflare, Route 53, GoDaddy, Namecheap)
* An active tieback brand account with a configured platform subdomain
* Admin or owner role on your tieback brand

## Step 1: Choose Your Custom Hostname

Select a subdomain on your domain to use for passports. Common choices:

| Hostname               | Use Case                           |
| ---------------------- | ---------------------------------- |
| `passport.mybrand.com` | Dedicated passport subdomain       |
| `dpp.mybrand.com`      | Digital Product Passport subdomain |
| `product.mybrand.com`  | Product information subdomain      |

> **Note**
>
> We recommend using a dedicated subdomain rather than your root domain. Apex/root domains are not
> supported; you must use a subdomain.

## Step 2: Create a DNS CNAME Record

Add a CNAME record at your DNS provider:

| Field      | Value                                    |
| ---------- | ---------------------------------------- |
| **Type**   | `CNAME`                                  |
| **Name**   | Your chosen subdomain (e.g., `passport`) |
| **Target** | `<brand>.tieback.io`                     |
| **TTL**    | `Auto` or `300` (5 minutes)              |

**Example:**

```
passport.mybrand.com  CNAME  mybrand.tieback.io
```

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

## Step 3: Add the Domain in tieback

After creating the DNS record:

1. Navigate to **Settings → Domains** in the tieback dashboard
2. Enter your custom hostname in the Custom Domain field
3. Click **Add custom domain**

The system will begin verifying your DNS and provisioning an SSL certificate.

## Step 4: Wait for Activation

DNS changes and SSL provisioning take time:

| Stage                        | Typical Time                                        |
| ---------------------------- | --------------------------------------------------- |
| DNS propagation              | Minutes to 1 hour (up to 24–48 hours in some cases) |
| SSL certificate provisioning | 5–15 minutes after DNS verification                 |

Click **Refresh Status** in Settings → Domains to check progress.

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

## Step 5: Test Your Custom Hostname

Once active, test your custom hostname:

```bash
curl -I https://passport.mybrand.com/01/<your-GTIN>
```

**Expected result:**

* `HTTP/2 302` with a `Location` header pointing to your public passport page (e.g., `/p/<product-id>`)

You can also test the passport page directly:

```bash
curl -I https://passport.mybrand.com/p/<product-id>
```

**Expected result:**

* `HTTP/2 200`: the passport page renders successfully

## What's Supported on Custom Hostnames

Custom hostnames support **public consumer paths**:

| Path                               | Supported | Purpose                        |
| ---------------------------------- | --------- | ------------------------------ |
| `/01/<GTIN>`                       | ✅ Yes     | GS1 Digital Link resolution    |
| `/mu/<id>`, `/mb/<id>`, `/ml/<id>` | ✅ Yes     | Fallback identifier resolution |
| `/p/<id>`                          | ✅ Yes     | Public passport page rendering |
| `/dashboard`, `/settings`, etc.    | ❌ No      | Use platform subdomain         |

Dashboard and application access should continue to use your platform subdomain (`<brand>.tieback.io`).

## Troubleshooting

For detailed troubleshooting, see the [Custom Hostname Troubleshooting](/domains-custom-hostnames/troubleshooting) guide.

### Quick Checks

* **DNS not propagating**: verify the CNAME is correct using [dnschecker.org](https://dnschecker.org) and wait up to 24–48 hours
* **SSL not provisioning**: check for CAA records that may block certificate issuance
* **403 on dashboard paths**: this is expected; custom hostnames support public paths only
* **404 on resolver paths**: verify the product exists and has been minted
* **CNAME target wrong**: must be `<brand>.tieback.io`, not `tieback.io` or an IP address

## Fallback

Your platform subdomain (`<brand>.tieback.io`) always remains active. If you experience issues with your custom hostname, your existing QR codes using the platform subdomain will continue to work.

## Related Docs

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