Whitelabeling enables a seamless branded experience by using your custom subdomains for various Piano Piano Subscriptions products, including Identity Management, Management + Billing, and Composer. It helps address known issues with certain browsers that may block Piano scripts, and also ensures smoother integration of Identity Management with popular password managers.
Why whitelabel
-
Authentication happens on your domain. Browsers save passwords under your domain (for example,
publicationname.com) instead oftinypass.comorpiano.io. iOS authentication prompts also reference your domain, users see "Sign in to publicationname.com" instead of "Sign in to tinypass.com." -
First-party cookie behavior. A custom domain makes the relevant cookies first-party and allows them to be set via
Set-Cookieheaders instead of JavaScript. This is especially useful for Composer and Identity Management, where browser restrictions like Safari ITP and Chrome's third-party cookie policies can shorten cookie lifecycles. -
Reduced blocking risk. Some ad blockers, VPNs, and DNS sinkholes are more likely to block well-known third-party domains. Serving Piano endpoints from your own domain reduces these issues in many environments.
Here's a high-level overview of how the whitelabeling process works:
→ Piano creates TXT records
→ Client updates DNS with TXT records
→ Piano validates the TXT records
→ Piano provides CNAME records for the custom domain
→ Client updates DNS with CNAME records
→ Piano validates the CNAME records
→ Client modifies Piano scripts to use the custom domain
If you're only looking to whitelabel the domain for Identity Management, you can find the instructions here.
Detailed Steps for Full Domain Whitelabeling
Step 1: Decide on Your Subdomains
Select the custom subdomains for your whitelabel setup. Example configurations might include:
-
ID: auth.yourdomain.com
-
Composer: c2.yourdomain.com
-
Management + Billing: vx.yourdomain.com
-
CDN (optional): cdn.yourdomain.com
Please ensure that the subdomains you provide for whitelabeling are not already in use for other purposes within your organization. These subdomains should be reserved exclusively for Piano whitelabeling.
Subdomain Limitations
Clients are required to use dedicated subdomains for each product (e.g., ID, Management + Billing, etc.). Additionally, subdomains generally need to be unique across environments, meaning that separate subdomains should be used for Sandbox and Production environments. The only exception may be the CDN, which could potentially be shared between Sandbox and Production.
Step 2: Configure DNS TXT Records for Verification
To initiate the whitelabeling process, you will need to add new DNS TXT records for domain control validation (DCV).
This process requires Piano involvement, and you can contact our Piano Support at support@piano.io to initiate the whitelabeling process.
Add the TXT records provided by Piano Support to your DNS for each subdomain to facilitate verification. These records are crucial for certificate and hostname validation.
Note: This needs to be requested and implemented separately for each Piano environment.
To validate the SSL certificate, the client must add the TXT entries provided by the Support Team in their hostname's authoritative DNS. This is a one-time validation. The TXT records can be removed after the final step of the setup is completed.
Important: The CNAME records added in Step 3 must remain in place permanently.
Below are two sample TXT records for reference:
-
_acme-challenge.auth.yourdomain.com TXT [provided value]
-
_cf-custom-hostname.auth.yourdomain.com TXT [provided value]
After adding the records, allow time for DNS propagation. This typically takes less than 24 hours.
These records serve as proof of ownership for the authentication subdomain and are required to enable secure HTTPS connections via Cloudflare.
Step 3: Replace TXT Records with CNAME Records
Once Piano Support confirms successful verification and DNS propagation:
-
You may remove the TXT records used for domain validation.
-
Then, add the CNAME records for each custom subdomain as provided by Piano Support.
For example, to configure the Identity Management subdomain:
-
auth.yourdomain.com CNAME auth-piano-domain.tinypass.com
Repeat this process for the other products, using the exact CNAME targets shared by Piano Support.
Step 4: Update Your Integration Script
Note: Please wait to proceed with this step until Piano Support has confirmed that domain verification is complete and the full whitelabeling setup has been finalized.
Update the integration script to reference your whitelabeled subdomains. This can be done either:
-
In your Piano dashboard: Products → Composer → Integrate → Edit Source, or
-
Directly in your custom implementation on your website.
Update the script as follows (replace yourdomain.com and the subdomains with those you selected in Step 1):
tp.push(['setComposerHost','https://c2.yourdomain.com']);
tp.push(['setPianoIdUrl', 'https://auth.yourdomain.com']);
tp.push(['setEndpoint', 'https://vx.yourdomain.com']);
tp.push(['setStaticDomain', 'https://cdn.yourdomain.com']);
Ensure URLs begin with https:// and to include the custom subdomains you have chosen.
If you've chosen to whitelabel the CDN as well, you need to load the JS SDK from the new URL https://cdn.yourdomain.com/api/tinypass.min.js instead of the default https://cdn.piano.io/api/tinypass.min.js.
If you are using the Composer load script, ensure it is also loaded from your custom domain. For example, your pages should reference https://c2.yourdomain.com/xbuilder/experience/load?aid=<aid> instead of https://api.piano.io/xbuilder/experience/load?aid=<aid>.
Please also note that with full domain whitelabeling, tp.push(["setSandbox", true]); must not be used in either Sandbox or Production environments.
Step 5: Configure Identity Management Settings
Authorized JavaScript Origins
To ensure secure authentication, update the authorized JavaScript origins in your Identity Management settings under Business → User Provider → Identity Management → Authorized tab, by adding your whitelabeled subdomain, for example, https://auth.yourdomain.com.
Deployment Host
In your Piano dashboard, navigate to Business → User Provider → Identity Management → Other Login Methods. Update the Deployment Host to reflect the whitelabel subdomain, e.g., auth.yourdomain.com.
Redirect URI
Still under the Authorized tab, add your whitelabeled domain as a Redirect URI, e.g., for example, https://auth.yourdomain.com.
Social Login Callback URLs
For social login functionality, update the authorized redirect URIs in the dashboards of the social platforms you integrate with Identity Management (e.g. Google, Facebook, etc.) to point to your whitelabeled domain's social login callback URL, like https://auth.yourdomain.com/id/api/v1/identity/login/social/callback.
Google reCAPTCHA (if enabled)
If you are using Google reCAPTCHA, register your whitelabeled domain in the Google reCAPTCHA admin console to ensure proper operation.
Additional Notes
-
Ensure cross-origin requests are correctly configured to prevent CORS errors.
-
Confirm that cookies set by the new subdomains are correctly handled.
-
Update any redirects or callback URLs used in third-party integrations.
-
Users may need to re-save their passwords for the new domain or adjust their browser and password manager settings.
Step 6: Testing and Verification
Once all DNS changes have propagated and integration scripts and settings are updated:
-
Test the entire user flow.
-
Confirm that all requests and resources, including JavaScript files and API calls, use your custom subdomains.
By completing these steps, you can ensure that all Piano-related traffic routes through your branded domains, delivering a cohesive user experience and enhancing compatibility with ad blockers and privacy tools.
Warning: Any domains that are considered invalid, where the whitelabeling setup was never completed, and which were created at least 90 days ago, will be eligible for deletion. In case of any questions, please contact our Support team at support@piano.io.
Make sure to replace placeholders like [provided value] and yourdomain.com with your specific information.
Step 7: Troubleshooting
If something is not working after cutover, check the items below before contacting Support.
CNAME conflicts with existing records
A hostname cannot have a CNAME if it already has other records at the same name. Remove or replace the conflicting records.
Old verification records left in place
Leftover TXT records on a separate name (like _acme-challenge.<subdomain>) are usually fine, but records that conflict with the final CNAME at the same hostname will break the setup. Remove anything that shares a name with the final CNAME.
CORS errors after cutover
If browser console errors mention CORS, confirm that the whitelabeled domain is listed under Business → User Provider → Identity Management → Authorized → Authorized JavaScript Origins, along with any other relevant allowlists.
Password manager prompts
Saved passwords associated with the old Piano domain do not automatically transfer to the new whitelabeled domain. Users may need to save their credentials again under the new domain.
Ad blockers still interfering
Whitelabeling reduces blocking, but it cannot prevent all client-side blocking. If users continue to experience issues, consider showing a message prompting them to disable ad blockers, or implement an ad blocker detection approach.