Modular White-Label Architecture
Passinstance provides white-label branding as modular capabilities managed through White-Label Domains API (/api/v1/white-labeling/* and Dashboard Workspace Settings -> Branding /settings/workspace/branding plus Messaging -> SMTP /settings/workspace/messaging/smtp). Organizations and agencies can customize three distinct touchpoints per workspace:
-
1
Vanity Pass & Portal Domains (domain surface type): Serve smart distribution links (
/d/:slug,/s/:token), PassFlow enrollment pages, backoffice UI, workflow portals, docs, or support portals from your own subdomain (wallet.yourbrand.com) with automated TLS termination. -
2
Branded Transactional Email & Custom SMTP: Deliver pass distribution and recovery emails from your corporate domain with verified SPF and DKIM signatures, or route all outbound email through your own mail server via our encrypted Custom SMTP relay add-on.
-
3
Portal & Console Theming (
request payload): Customize color schemes, dark/light logos, favicons, andpoweredByEnabledsettings across customer and staff interfaces.
White-Labeling API Reference (White-Label Domains API)
All white-label configuration endpoints are scoped to the active tenant workspace:
| Endpoint Path | Method | Auth | Functionality |
|---|---|---|---|
/api/v1/white-labeling/configuration | GET | Bearer (whitelabel:view) | Retrieves the complete workspace branding configuration. |
/api/v1/white-labeling/features | GET | Bearer (whitelabel:view) | Returns which white-label add-on capabilities are unlocked on the workspace plan. |
/api/v1/white-labeling/vanity-urls | GET | Bearer (whitelabel:manage) | Lists configured vanity domains and their DNS/SSL status. |
/api/v1/white-labeling/vanity-urls | POST | Bearer (whitelabel:manage) | Registers a new vanity domain (request payload) and generates DNS verification tokens. |
/api/v1/white-labeling/vanity-urls/:id | DELETE | Bearer (whitelabel:manage) | Removes a vanity domain and reverts smart links to default platform routing. |
/api/v1/white-labeling/domains/:id/refresh | POST | Bearer | Triggers immediate DNS lookup for CNAME and TXT records. |
/api/v1/white-labeling/domains/:id/certificate-ready | POST | Bearer | Confirms SSL/TLS certificate issuance and activates HTTPS traffic termination. |
/api/v1/white-labeling/email | GET / POST / DELETE | Bearer | Reads, creates (request payload), or removes branded email sender settings and SPF/DKIM records. |
/api/v1/white-labeling/email/refresh | POST | Bearer | Re-checks live DNS records for SPF alignment and DKIM selector propagation. |
/api/v1/white-labeling/email/verify | POST | Bearer | Confirms domain verification token and promotes the sender to active status. |
/api/v1/white-labeling/theme | GET / PUT / DELETE | Bearer | Reads, updates (request payload), or resets portal colors and logos. |
Configuring a Vanity Download Domain (request payload & domain surface type)
Step 1: Register the Hostname and Target Surface
Send a POST /api/v1/white-labeling/vanity-urls request specifying the FQDN url, type from domain surface type (PASS_DOWNLOAD, PASS_FLOW, BACKEND_UI, WORKFLOW_ENGINE, API_DOCUMENTATION, SUPPORT_PORTAL), optional homePageRedirect, and isPrimary:
{
"url": "wallet.yourbrand.com",
"type": "PASS_DOWNLOAD",
"homePageRedirect": "https://www.yourbrand.com/wallet",
"isPrimary": true
}
Response (201 Created):
{
"id": "dom_94a1c02b",
"url": "wallet.yourbrand.com",
"type": "PASS_DOWNLOAD",
"status": "PENDING_DNS",
"cnameTarget": "cname.passinstance.com",
"txtRecordName": "_passinstance-verify.wallet.yourbrand.com",
"txtRecordValue": "pi-verify=7f8e9a10b2c3d4e5f6",
"sslStatus": "PENDING"
}
Step 2: Configure DNS & Refresh
Add the required CNAME record pointing to cname.passinstance.com and the TXT verification record in your DNS provider. Once propagated, trigger POST /api/v1/white-labeling/domains/:id/refresh followed by POST /api/v1/white-labeling/domains/:id/certificate-ready to finalize TLS provisioning.
Prerequisites: When configuring a vanity domain in Cloudflare or similar proxy networks, set the CNAME record to DNS Only (grey cloud) during initial verification so Passinstance can validate the target
cname.passinstance.comrecord and provision your managed TLS certificate without proxy interference.
Custom Sender Address & Custom SMTP Relay Add-on
Workspaces can choose between two methods for sending branded pass emails:
Method A: Platform managed email delivery with Domain Verification
Deliver emails through Passinstance's managed email delivery infrastructure in eu-central-1 (Frankfurt) using your own sender address (e.g. passes@yourbrand.com). You register your domain via POST /api/v1/white-labeling/email and add standard SPF (include:spf.passinstance.com) and DKIM CNAME records to your DNS provider.
Method B: Dedicated Custom SMTP Server Add-on (€20/mo)
For complete control and internal mail server compliance, workspaces can route all transactional emails and Delivery Center campaigns through their own email infrastructure (SendGrid, Mailgun, Microsoft 365, Google Workspace, Postmark, or private SMTP servers):
-
Pricing: Modular add-on at €20/month (
AddonType.OWN_SMTP, feature flagownSmtp). -
Flexible Ports: Supports port 587 (STARTTLS), port 465 (implicit SSL/TLS), port 2525 (alternative cloud submission), and port 25.
-
Anti-SSRF Host Security: Enforces
validateSmtpHostto block loopback addresses (127.0.0.1), RFC 1918 private IP ranges, and AWS instance metadata (169.254.169.254). -
encrypted storage Encryption: SMTP credentials are encrypted in encrypted secret storage (
smtp/{customerId}) and never stored in plaintext or logged. -
Preflight Verification: Verify server connectivity with an immediate test email via
POST /settings/smtp-config/test.
For complete step-by-step setup instructions and DNS alignment requirements, see the dedicated Your Own Sender Address & Custom SMTP Guide.
Configuring Portal Themes & Brand Colors
To style customer-facing pass distribution pages, PassFlow forms, and staff portals, update your workspace theme via PUT /api/v1/white-labeling/theme using request payload:
{
"logoUrl": "https://cdn.yourbrand.com/assets/logo.png",
"logoLightUrl": "https://cdn.yourbrand.com/assets/logo-light.png",
"logoDarkUrl": "https://cdn.yourbrand.com/assets/logo-dark.png",
"faviconUrl": "https://cdn.yourbrand.com/assets/favicon.ico",
"colorScheme": {
"primary": "#0F172A",
"secondary": "#2563EB",
"background": "#F8FAFC",
"text": "#020617",
"appName": "YourBrand Wallet",
"poweredByEnabled": false
}
}
Related Documentation
-
Your Own Sender Address & Custom SMTP — In-depth guide to configuring custom SMTP relays.
-
Email & SMS Delivery — Delivery Center campaigns and email templates.
-
Download Links & PassFlow — Smart link routing and PassFlow page settings.
-
White-Label Wallet Pass API — Enterprise white-label capabilities.
