Skip to content
Help Center Guide · Agencies & Partners
4 min readVerified 2026-11-16

Custom Branding & White-Label Options

Configure modular add-ons: custom download vanity domains, custom SMTP email senders, and optional white-label console branding.

In This Guide

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. 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. 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. 3
    Portal & Console Theming (request payload): Customize color schemes, dark/light logos, favicons, and poweredByEnabled settings across customer and staff interfaces.
SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
WHITE-LABEL DOMAIN & EMAIL VERIFICATION
STAGE 01 TENANT DNS PROVIDER (Cloudflare / Route53 / Custom DNS)
1
Vanity Domain CNAME: wallet.yourbrand.comcname.passinstance.com
2
Ownership TXT Record: _passinstance-verify.wallet.yourbrand.com
3
Email Auth Records: SPF include (v=spf1 include:spf.passinstance.com ~all) & DKIM
STAGE 02 WHITE-LABELING ENDPOINTS (/api/v1/white-labeling/*)
Resolves authoritative DNS records & validates ownership tokens
Provisions managed TLS/SSL certificates (/domains/:id/certificate-ready)
Activates custom SES/SMTP sender identity (/email/verify)

White-Labeling API Reference (White-Label Domains API)

All white-label configuration endpoints are scoped to the active tenant workspace:

Endpoint PathMethodAuthFunctionality
/api/v1/white-labeling/configurationGETBearer (whitelabel:view)Retrieves the complete workspace branding configuration.
/api/v1/white-labeling/featuresGETBearer (whitelabel:view)Returns which white-label add-on capabilities are unlocked on the workspace plan.
/api/v1/white-labeling/vanity-urlsGETBearer (whitelabel:manage)Lists configured vanity domains and their DNS/SSL status.
/api/v1/white-labeling/vanity-urlsPOSTBearer (whitelabel:manage)Registers a new vanity domain (request payload) and generates DNS verification tokens.
/api/v1/white-labeling/vanity-urls/:idDELETEBearer (whitelabel:manage)Removes a vanity domain and reverts smart links to default platform routing.
/api/v1/white-labeling/domains/:id/refreshPOSTBearerTriggers immediate DNS lookup for CNAME and TXT records.
/api/v1/white-labeling/domains/:id/certificate-readyPOSTBearerConfirms SSL/TLS certificate issuance and activates HTTPS traffic termination.
/api/v1/white-labeling/emailGET / POST / DELETEBearerReads, creates (request payload), or removes branded email sender settings and SPF/DKIM records.
/api/v1/white-labeling/email/refreshPOSTBearerRe-checks live DNS records for SPF alignment and DKIM selector propagation.
/api/v1/white-labeling/email/verifyPOSTBearerConfirms domain verification token and promotes the sender to active status.
/api/v1/white-labeling/themeGET / PUT / DELETEBearerReads, 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:

JSON
{
  "url": "wallet.yourbrand.com",
  "type": "PASS_DOWNLOAD",
  "homePageRedirect": "https://www.yourbrand.com/wallet",
  "isPrimary": true
}

Response (201 Created):

JSON
{
  "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.com record 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 flag ownSmtp).
  • Flexible Ports: Supports port 587 (STARTTLS), port 465 (implicit SSL/TLS), port 2525 (alternative cloud submission), and port 25.
  • Anti-SSRF Host Security: Enforces validateSmtpHost to 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:

JSON
{
  "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 Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.