Domains & Custom Hostnames

Resolver Domain Flow

Resolver Domain Flow

When a consumer scans a QR code on a product, the tieback Identity Resolver processes the request and redirects to the correct Digital Product Passport.

What Happens on Scan

Step-by-Step Flow

  1. Consumer scans a QR code printed on the product
  2. The QR code encodes a URL such as https://mybrand.tieback.io/01/5060999100032
  3. The request arrives at the Cloudflare edge
  4. The Tenant Proxy detects a resolver path (/01/) and forwards the request to the Resolution Engine
  5. The Resolution Engine calls the tieback backend with the hostname, GTIN, and any additional identifiers
  6. The backend resolves the identifier to a destination passport URL
  7. The consumer receives an HTTP 302 redirect to the public passport page (e.g., /p/<product-id>)
  8. The passport page renders the full Digital Product Passport experience on the same domain

Custom Hostname Flow

If the brand uses a custom hostname:

  1. Consumer scans a QR code with URL https://passport.mybrand.com/01/5060999100032
  2. DNS resolves the custom hostname via CNAME to mybrand.tieback.io
  3. Cloudflare routes the request through the custom hostname configuration
  4. The original hostname (passport.mybrand.com) is preserved and passed to the Resolution Engine
  5. Resolution proceeds identically — the backend uses the hostname to identify the brand
  6. The consumer is redirected to https://passport.mybrand.com/p/<product-id>
  7. The passport page renders on the brand’s custom domain

Two-Step Public Flow

tieback uses a deliberate two-step flow for scan resolution:

StepURL PatternPurpose
1. Scan URL/01/<GTIN>/21/<serial>Standards-compatible entry point (GS1 Digital Link)
2. Passport Page/p/<product-id>Clean rendering destination for the passport experience

This separation ensures that:

  • QR codes remain GS1-compatible for long-term interoperability
  • The passport page uses a clean, stable URL optimised for rendering
  • The redirect is transparent to the consumer — it happens instantly

For more details, see Resolver & Passport Rendering.

Supported Resolver Paths

/01/<GTIN>
/01/<GTIN>/10/<lot>
/01/<GTIN>/21/<serial>
/01/<GTIN>/10/<lot>/21/<serial>

Examples:

https://mybrand.tieback.io/01/5060999100032
https://mybrand.tieback.io/01/5060999100032/10/BATCH2024A
https://mybrand.tieback.io/01/5060999100032/21/SN00001

Fallback Identifiers

/mu/<mint-unit-id>
/mb/<mint-batch-id>
/ml/<mint-lot-id>

These paths resolve individual minted units, batches, or lots directly by their tieback identifier.

Response Behaviour

Successful Resolution

  • Status: 302 Found
  • Location: The public passport page URL (e.g., /p/<product-id>)
  • Cache-Control: Determined by the resolver (typically public, max-age=3600 or no-store)

Not Found

  • Status: 404 Not Found
  • Returned when the GTIN, serial, or identifier cannot be matched to a known product

Bot Detection

Social media bots (WhatsApp, Slack, Twitter, Discord, Facebook, LinkedIn, Telegram, Google) receive an HTML response with Open Graph meta tags instead of a redirect. This ensures proper link unfurling when passport links are shared.

Query Parameters

Any query parameters appended to the scan URL are preserved and forwarded to the destination passport URL. This supports analytics tracking, campaign attribution, and other use cases.

https://mybrand.tieback.io/01/5060999100032?utm_source=packaging
→ redirects to passport URL with ?utm_source=packaging appended