Skip to main content

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.
These options are intended to help the SDK feel native inside a partner product while keeping sensitive setup details managed by Narrative and the partner’s implementation team.

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 for bodyFontFamily and headingFontFamily; do not replace those values with Sohne:
  • Satoshi, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
  • system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
  • Georgia, "Times New Roman", Times, serif
  • ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace
The app treats the exact Satoshi preset above as the current Narrative default. This API value does not select Satoshi rendering in the hosted app. Uploaded font files are not supported in this release. When a partner uses custom font URLs, provide separate choices for body text and headings. Always agree a fallback font so the SDK remains readable if a remote font is unavailable.

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

The UUID in this example is illustrative. Use the actual tenant reference and returned asset URL for your integration.

Core theme tokens

These are the primary partner-facing tokens and should be the first set partners override:
  • primary
  • onPrimary
  • secondary
  • onSecondary
  • accent
  • highlight
  • background
  • surface
  • surfaceSubtle
  • secondarySubtle
  • foreground
  • muted
  • border

Advanced component tokens

Advanced tokens are feature-specific component colors (for example impactIconMain, 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/branding for 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:
  1. Resolve tenant context in host shell.
  2. Call /api/public/branding?tenantId=<TENANT_UUID> using the tenant’s public UUIDv4 reference, or tenant-authenticated /api/settings/branding.
  3. Apply returned branding tokens before mounting embedded widgets.
  4. Keep host shell and embedded widget tokens aligned to avoid visual mismatch.

Validation and fallbacks

  • Omitting tenantId from a public branding query selects the configured default tenant. Supplying an unknown tenant UUID returns 404.
  • 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:
  1. Tenant A and Tenant B have distinct colors, typography, and email branding values.
  2. GET /api/settings/branding reflects tenant-specific values without code changes.
  3. Onboarding completion email uses tenant-specific subject and signature branding.
  4. Invalid branding payloads are rejected by API schema validation.