Overview
Partners manage tenant-level colours, typography and email branding through the settings APIs. These controls are separate from the SDK end-user Settings UI. Product name, logo and favicon are not fields in the branding payload documented here. Partner product-referral preferences are managed separately from these visual branding endpoints.What’s new in v1.9.0
Partner integrations that manage Narrative branding need an update for v1.9.0. The Narrative default theme uses Sohne typography and restrained accents. Supported font choices and agreed partner fonts remain available. See the v1.9.0 release notes for compatibility and sign-in changes.What’s new in v1.8.9
The existing partner-branded sign-in experience is retained when campaign tracking parameters accompany its designated entry link. This uses the existing branding selection; it does not add a new tenant setting or change authentication. See the v1.8.9 release notes for details.What’s new in v1.8.8
An explicit partner product-referral opt-out is respected across Coach, Money, Growth and Projects. The existing tenant referral configuration controls this behaviour; no new end-user branding control or public branding field is introduced.What’s new in v1.5.7
v1.5.7 expands white-labelling from a basic visual theme into a broader partner experience.
- Partners can use richer colour theming across the product surface.
- Body and heading typography can be configured separately.
- Approved remote brand font URLs are supported for tenant themes.
- Partner-specific coaching tone can be configured alongside visual branding.
- Partner product referral behaviour can be aligned to the tenant’s customer support or product journey.
- The first partner theme is delivered through this model.
Typography
Typography includes preset font stacks and approved remote custom font URLs for tenant configurations. The hosted app’s Narrative default is Sohne with a system fallback. The API continues to use the following preset values forbodyFontFamily and headingFontFamily; do not replace those values with Sohne:
Satoshi, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serifsystem-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serifGeorgia, "Times New Roman", Times, serifui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace
Partner setup checklist
Before launching a white-labelled tenant experience, confirm the following with the partner team:- Brand colours for primary actions, backgrounds, surfaces, borders, and muted text.
- Heading and body typography, including any approved remote font URLs.
- Logo and email branding expectations where enabled.
- Product naming and support contact copy that users will recognise.
- Coaching tone and vocabulary for the tenant audience.
- Any partner product referral language that should appear when users ask about partner-specific products.
Default typography API values
API endpoints
Supported
assetKey values:
email-signature-logo
tenantId in the public branding query and asset route is the tenant’s public UUIDv4 reference, not a numeric identifier. A malformed reference returns 422; an unknown tenant reference returns 404.
Request and response shape
Core theme tokens
These are the primary partner-facing tokens and should be the first set partners override:primaryonPrimarysecondaryonSecondaryaccenthighlightbackgroundsurfacesurfaceSubtlesecondarySubtleforegroundmutedborder
Advanced component tokens
Advanced tokens are feature-specific component colors (for exampleimpactIconMain, actionStepsBg, spendingThisAvg, actionBarUrgent, riskBg, sectionIconDrivers).
These remain supported, but they are implementation-level and will be consolidated in a future design system release.
Runtime behavior
- Before sign-in, the web app loads
/api/public/branding. - After authentication, the web app loads
/api/settings/brandingfor the active tenant. - Branding is applied to CSS variables.
- Completion emails use tenant branding values when provided.
Embedded surfaces
Embedded hosts should load tenant branding before boot and apply the same token map used by the full app shell. Recommended sequence:- Resolve tenant context in host shell.
- Call
/api/public/branding?tenantId=<TENANT_UUID>using the tenant’s public UUIDv4 reference, or tenant-authenticated/api/settings/branding. - Apply returned branding tokens before mounting embedded widgets.
- Keep host shell and embedded widget tokens aligned to avoid visual mismatch.
Validation and fallbacks
- Omitting
tenantIdfrom a public branding query selects the configured default tenant. Supplying an unknown tenant UUID returns404. - Missing individual fields also fall back to defaults.
- Theme and email template JSON are validated against SSOT schemas.
Test checklist
Validate with at least two tenant configurations:- Tenant A and Tenant B have distinct colors, typography, and email branding values.
GET /api/settings/brandingreflects tenant-specific values without code changes.- Onboarding completion email uses tenant-specific subject and signature branding.
- Invalid branding payloads are rejected by API schema validation.