Modulare White-Label-Architektur
Passinstance stellt White-Label-Branding als modulare Funktionen bereit, die über den White-Label Domains API (/api/v1/white-labeling/* sowie im Dashboard unter Workspace-Einstellungen -> Branding /settings/workspace/branding und Messaging -> SMTP /settings/workspace/messaging/smtp) verwaltet werden. Unternehmen und Agenturen können pro Workspace drei verschiedene Kontaktpunkte individuell anpassen:
-
1
Vanity-Domains für Karten & Portale (domain surface type): Stellen Sie intelligente Verteilungslinks (
/d/:slug,/s/:token), PassFlow-Registrierungsseiten, die Backoffice-Benutzeroberfläche, Workflow-Portale, Dokumentationen oder Support-Portale über Ihre eigene Subdomain (wallet.yourbrand.com) mit automatisierter TLS-Terminierung bereit. -
2
Gebrandete Transaktions-E-Mails: Versenden Sie E-Mails zur Kartenverteilung und Wiederherstellung über Ihre eigene Domain mit verifizierten SPF- und DKIM-Signaturen (
request payload). -
3
Portal- & Konsolen-Theming (
request payload): Passen Sie Farbschemata, helle und dunkle Logos, Favicons sowie die EinstellungpoweredByEnabledan.
White-Labeling-API-Referenz (White-Label Domains API)
Alle Endpunkte zur White-Label-Konfiguration sind auf den aktiven Mandanten-Workspace begrenzt:
| Endpunktpfad | Methode | Authentifizierung | Funktionalität |
|---|---|---|---|
/api/v1/white-labeling/configuration | GET | Bearer (whitelabel:view) | Ruft die vollständige Branding-Konfiguration des Workspaces ab. |
/api/v1/white-labeling/features | GET | Bearer (whitelabel:view) | Gibt zurück, welche White-Label-Add-on-Funktionen im Workspace-Tarif freigeschaltet sind. |
/api/v1/white-labeling/vanity-urls | GET | Bearer (whitelabel:manage) | Listet konfigurierte Vanity-Domains sowie deren DNS-/SSL-Status auf. |
/api/v1/white-labeling/vanity-urls | POST | Bearer (whitelabel:manage) | Registriert eine neue Vanity-Domain (request payload) und generiert DNS-Verifizierungs-Tokens. |
/api/v1/white-labeling/vanity-urls/:id | DELETE | Bearer (whitelabel:manage) | Entfernt eine Vanity-Domain und stellt Smart Links auf das Standard-Plattform-Routing zurück. |
/api/v1/white-labeling/domains/:id/refresh | POST | Bearer | Löst eine sofortige DNS-Abfrage für CNAME- und TXT-Einträge aus. |
/api/v1/white-labeling/domains/:id/certificate-ready | POST | Bearer | Bestätigt die Ausstellung des SSL-/TLS-Zertifikats und aktiviert die HTTPS-Datenverkehrsterminierung. |
/api/v1/white-labeling/email | GET / POST / DELETE | Bearer | Liest, erstellt (request payload) oder entfernt Einstellungen für gebrandete E-Mail-Absender sowie SPF-/DKIM-Einträge. |
/api/v1/white-labeling/email/refresh | POST | Bearer | Prüft aktuelle DNS-Einträge erneut auf SPF-Abgleich und DKIM-Selektor-Propagierung. |
/api/v1/white-labeling/email/verify | POST | Bearer | Bestätigt das Domain-Verifizierungs-Token und stuft den Absender in den aktiven Status hoch. |
/api/v1/white-labeling/theme | GET / PUT / DELETE | Bearer | Liest, aktualisiert (request payload) oder setzt Portalfarben und Logos zurück. |
Konfigurieren einer Vanity-Download-Domain (request payload & domain surface type)
Schritt 1: Hostnamen und Zieloberfläche registrieren
Senden Sie eine Anfrage an POST /api/v1/white-labeling/vanity-urls und geben Sie die FQDN-url, den type aus domain surface type (PASS_DOWNLOAD, PASS_FLOW, BACKEND_UI, WORKFLOW_ENGINE, API_DOCUMENTATION, SUPPORT_PORTAL), optional homePageRedirect sowie isPrimary an:
{
"url": "wallet.yourbrand.com",
"type": "PASS_DOWNLOAD",
"homePageRedirect": "https://www.yourbrand.com/wallet",
"isPrimary": true
}
Antwort (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"
}
Schritt 2: DNS konfigurieren & aktualisieren
Fügen Sie bei Ihrem DNS-Anbieter den erforderlichen CNAME-Eintrag, der auf cname.passinstance.com verweist, sowie den TXT-Verifizierungseintrag hinzu. Sobald die Einträge propagiert sind, lösen Sie POST /api/v1/white-labeling/domains/:id/refresh gefolgt von POST /api/v1/white-labeling/domains/:id/certificate-ready aus, um die TLS-Bereitstellung abzuschließen.
Konfigurieren von gebrandetem E-Mail-Versand & Portal-Themes
Um E-Mails zur Kartenausgabe und Wiederherstellung über Ihre eigene Domain zu versenden, registrieren Sie Ihre Absenderidentität ({ senderEmail, senderName?, spfRecord?, dkimRecord?, dkimSelector? }) über POST /api/v1/white-labeling/email und validieren Sie den SPF-/DKIM-Abgleich mit POST /api/v1/white-labeling/email/refresh sowie POST /api/v1/white-labeling/email/verify.
Um Ihre kundenorientierten Verteilungsseiten individuell zu gestalten, aktualisieren Sie das Theme über PUT /api/v1/white-labeling/theme mithilfe des 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
}
}
Voraussetzungen: Wenn Sie eine Vanity-Domain in Cloudflare oder ähnlichen Proxy-Netzwerken konfigurieren, stellen Sie den CNAME-Eintrag während der ersten Verifizierung auf DNS Only (graue Wolke), damit Passinstance den Zieleintrag
cname.passinstance.comvalidieren und Ihr verwaltetes TLS-Zertifikat ohne Proxy-Interferenzen bereitstellen kann.
Entdecken Sie alle architektonischen Details auf der Seite White-Label Wallet Pass API oder verwalten Sie Add-on-Abonnements unter Preise.
