Why Do I Need to Whitelabel My Domain?

What Is Domain Whitelabeling?

By default, Piano products are served from Piano-owned domains such as id.piano.io, c2.piano.io, buy.piano.io, and cdn.tinypass.com. Domain whitelabeling allows you to replace these with subdomains that you own (for example, auth.example.com, c2.example.com), so that Piano services appear to your users and their browsers as first-party resources on your domain.

Why Do I Need to Whitelabel My Domain?

Modern browsers, ad blockers, corporate firewalls, and privacy-focused browser extensions increasingly restrict or block requests to third-party domains that they classify as trackers. Because Piano's default domains are shared across many customers, they can be flagged by these systems, even though the requests are essential to your site's functionality (login, paywalls, content access, etc.).

Whitelabeling moves Piano services onto your own domain, making them first-party requests that are far less likely to be blocked.

Common Symptoms Without Whitelabeling

If you are not using whitelabeled domains, you may observe one or more of the following issues:

• Piano scripts or experiences intermittently fail to load for some users.

• Login or registration modals fail to open, open and close immediately, or complete the OAuth flow but do not finish the login.

• Users in restrictive network environments (corporate VPNs, firewalls, or privacy-focused browsers) report consistent failures.

• Browser developer tools show blocked requests to Piano domains (e.g., id.piano.io, c2.piano.io).

Why These Problems Occur

These issues are caused by mechanisms outside of Piano's control:

• Enhanced Tracking Prevention (ETP/ITP): Browsers such as Safari and Firefox automatically restrict cross-site cookies and requests to domains classified as trackers.

• Ad blockers and privacy extensions: Extensions like uBlock Origin, AdGuard, or Privacy Badger maintain blocklists that may include Piano's shared domains.

• Corporate firewalls and network policies: Some organizations block categories of domains that include third-party analytics or paywall services.

Since these restrictions target third-party domains, serving Piano from your own first-party subdomain effectively avoids them.

What Are My Whitelabeling Options?

Piano ID Whitelabeling (Authentication Only)

This option whitelabels only the Piano ID authentication host, replacing the default id.piano.io with a subdomain you own (for example, auth.example.com). It covers login, registration, password reset, and social login callback flows.

This is suitable if your primary concern is authentication reliability and you are not experiencing blocking issues with other Piano services.

Full-Domain Whitelabeling (Recommended)

This option whitelabels all Piano service hosts, providing the most comprehensive protection against blocking. A typical full-domain setup replaces the following:

Full-domain whitelabeling is recommended if you want to minimize the risk of any Piano functionality being blocked.

What Does the Setup Involve?

At a high level, whitelabeling requires changes in three areas:

1. DNS configuration: You create dedicated subdomains and add DNS records (TXT for validation, then CNAME for routing) as provided by Piano.

2. JavaScript integration updates: You update your Piano SDK initialization code to point to your new first-party hosts instead of the default Piano domains.

3. Piano Dashboard updates: You update settings in Piano ID (Authorized JavaScript Origins, Authorized Redirect URIs, and Deployment Host) to reflect the new domains.

For detailed, step-by-step setup instructions, refer to the guides linked in the Section here.

Will Whitelabeling Affect My Social Login Setup?

Yes. If you use social login providers (e.g. Google, Facebook, LinkedIn, Apple), you will need to update each provider's OAuth configuration to include the new callback URL on your whitelabeled domain. The callback URL format is typically:

https://auth.example.com/id/api/v1/identity/login/social/callback

Key points to keep in mind:

• Each social provider's console must be updated with the exact redirect URI (scheme + host + path), no wildcards are allowed.

• During the transition period, you may optionally keep the old Piano-hosted callback URIs in the provider consoles alongside the new ones, but avoid mixing hosts on the same page load.

• A mismatch between the setPianoIdUrl value in your JavaScript, the Deployment Host in the Piano Dashboard, and the redirect URIs in social provider consoles is the most common cause of social login failures after whitelabeling.

Things to Keep in Mind

• Do not mix default and whitelabeled hosts on the same page. For example, loading Piano ID from your whitelabeled domain while experiences still load from c2.piano.io can cause CORS, cookie, and authentication inconsistencies.

• Password managers and autofill: After switching domains, users' saved credentials may not autofill because browsers store passwords per domain. Users may need to re-save their credentials under the new host.

• Test in a staging or sandbox environment first when possible. If you cannot mirror DNS easily, test during a low-traffic window and use fresh browser sessions (Incognito/Private) to avoid cache and cookie conflicts.

• DNS proxying (e.g., Cloudflare "proxied" mode) can interfere with validation and routing. If you experience unexpected behavior, confirm whether the DNS record should be set to DNS-only mode.

Detailed Setup Guides

For complete technical instructions on configuring domain whitelabeling, refer to the following documentation:

• Full Domain Whitelabeling — Covers DNS setup, JavaScript SDK changes, and Piano Dashboard configuration for all Piano services.

• Domain Whitelabeling for Piano ID — Covers whitelabeling specifically for Piano ID authentication, including social login provider updates.

Last updated: June 25, 2026