> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrativebanking.com/llms.txt
> Use this file to discover all available pages before exploring further.

# White-labeling guide

> Configure tenant-level branding for colors, typography, and email templates without code changes.

## Overview

Narrative SDK supports tenant-level white-label configuration through backend settings APIs.
Branding is customer-managed and is not exposed in the SDK end-user Settings UI.
Tenant resolution is database-backed; default tenant comes from `n_tenants` rather than a hardcoded auth tenant id.

Product name, logo, and favicon are not part of the tenant branding configuration payload in this release.
Some tenant-specific runtime behavior, such as internal partner referral policy used by Coach, is stored server-side and is not exposed by the public branding endpoints documented here.

## 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 Funding Circle pilot theme is the first partner theme 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 scope in this release

Typography includes preset font stacks and approved remote custom font URLs for tenant configurations.

Supported typography preset values:

* `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`

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 settings snapshot

```json theme={null}
{
  "typography": {
    "bodyFontFamily": "Satoshi, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif",
    "headingFontFamily": "Satoshi, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
  }
}
```

## API endpoints

| Endpoint                                            | Method | Auth | Purpose                                           |
| --------------------------------------------------- | ------ | ---- | ------------------------------------------------- |
| `/api/public/branding`                              | `GET`  | No   | Read public/default branding used before sign-in. |
| `/api/settings/branding`                            | `GET`  | Yes  | Read current tenant branding.                     |
| `/api/public/branding/assets/{tenantId}/{assetKey}` | `GET`  | No   | Publicly serves uploaded branding assets.         |

Supported `assetKey` values:

* `email-signature-logo`

## Request and response shape

```json theme={null}
{
  "branding": {
    "colors": {
      "primary": "#0F5BFF",
      "onPrimary": "#FFFFFF",
      "secondary": "#0A8A6B",
      "onSecondary": "#FFFFFF",
      "secondarySubtle": "#D4EFE9",
      "accent": "#1199EE",
      "highlight": "#7A5CFF",
      "background": "#F7F8FA",
      "surface": "#FFFFFF",
      "surfaceSubtle": "#F1F4F8",
      "foreground": "#101828",
      "muted": "#667085",
      "border": "#D0D5DD"
    },
    "typography": {
      "bodyFontFamily": "Satoshi, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
      "headingFontFamily": "Satoshi, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
    },
    "emailTemplate": {
      "supportEmail": "support@acme.example",
      "signatureName": "The Acme team",
      "signatureLogoUrl": "/api/public/branding/assets/1001/email-signature-logo?v=<asset-id>",
      "onboardingCompletionSubject": "Your Acme workspace is ready",
      "onboardingCompletionCtaLabel": "Open my workspace"
    }
  }
}
```

## 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_ID>` 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

* Missing tenant row falls back to Narrative defaults.
* 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.