Skip to main content

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.

​
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

{
  "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

EndpointMethodAuthPurpose
/api/public/brandingGETNoRead public/default branding used before sign-in.
/api/settings/brandingGETYesRead current tenant branding.
/api/public/branding/assets/{tenantId}/{assetKey}GETNoPublicly serves uploaded branding assets.
Supported assetKey values:
  • email-signature-logo

​
Request and response shape

{
  "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.