Custom Hostname Setup

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:

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

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:

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