Skip to main content

​
Configuration reference

Use this page as the detailed configuration reference for Narrative SDK tenant integrations.
This page focuses on integration configuration and auth contract details rather than internal endpoint schemas.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/frontend-shell.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=13c676d362a2a3a7a60bfa0fae245ad6

Frontend runtime

Base URLs, loader script, mount target, widget selection, and embed-token handoff in the browser.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/chart-line.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=06f41cec1f394b05dee7a2a65f657297

UI theme customization

Customize primary color, text color, surface backgrounds, and font family to match your product UI.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/lock.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=be29c8f389110e9dd5032501c0e8f00b

Backend secrets

Connected App identifiers and signing secrets that must stay on the tenant backend.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/link-handoff.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=710c716f96a2cf04ebe7fa38257b5ea1

Embed token contract

JWT claims, TTL guidance, and validation rules required before NSDK can issue scoped session tokens.

​
Configuration groups

Use these values in the tenant frontend when loading the SDK and mounting a widget container.
ParameterTypeRequiredDefaultValidation / ruleDescription
NSDK_BASE_URLstringYesNoneMust be a valid HTTPS base URL in production.Hosted Narrative SDK frontend origin used to load nsdk-loader.js.
data-nsdkstring / boolean-like attributeYesNoneSet to true.Marks the container as an SDK mount target.
data-nsdk-widgetstringYes for declarative mountNo documented fallback; use insights unless otherwise provisioned.Must match a widget supported by your provisioned SDK experience.Selects which widget the container should boot.
data-nsdk-tokenstringYesNoneMust be a valid short-lived Embed Token.Passes the tenant-signed Embed Token to the SDK container.
mountstring CSS selectorYes for imperative bootNoneSelector must resolve to one DOM node.Imperative alternative to declarative container boot.
widgets[].typestringYes for imperative bootNoneMust match an enabled widget type.Widget list passed to NSDK('boot', ...).
embedTokenstringYes for imperative bootNoneSame validation as data-nsdk-token.Embed token passed through imperative mode.
These values belong on the tenant backend only. They are used when minting the Embed Token.
ParameterTypeRequiredDefaultValidation / ruleDescription
NSDK_CONNECTED_APP_CLIENT_IDstringYesNoneMust match the Connected App provisioned in Narrative SDK.Used as the JWT iss claim when minting Embed Tokens.
NSDK_CONNECTED_APP_SECRET_KEYstringYesNoneKeep server-side only; never expose to browser code.HS256 signing key used to sign the Embed Token.
/your-embed-token-endpointHTTP routeYesNoneShould require an authenticated tenant user session.Backend endpoint that returns a freshly signed Embed Token to the frontend.
The Embed Token is the configuration object with the most validation requirements. NSDK will reject the token if required claims are missing or malformed.
Claim / fieldTypeRequiredDefaultValidation / ruleDescription
issstringYesNoneMust equal NSDK_CONNECTED_APP_CLIENT_ID.Identifies the tenant Connected App issuing the token.
substringYesNoneMust be a stable tenant user identifier.Represents the end user in tenant scope.
audstringYesNoneMust be exactly nsdk-embed.Audience check for embedded SDK token exchange.
iatnumberYesNoneUnix timestamp in seconds.Issued-at time.
expnumberYesNoneUnix timestamp in seconds; 5-15 minutes recommended.Expiry time for the embed token.
jtistringYesNoneShould be unique per token.Unique token id for replay-control and traceability.
nsdk.user.namestringYesNoneNon-empty string.User display name available to the SDK session.
nsdk.user.emailstringYesNoneShould be a valid email address.User email available to the SDK session.
nsdk.metadataobjectNoOmittedKeep small and non-sensitive.Optional tenant-defined metadata associated with the session.

​
UI theme customization

Assume your tenant integration already enables runtime UI theming. You can override colors and typography from the host application.
TokenPurposeExample
--nsdk-color-primaryMain brand action color#FF5418
--nsdk-color-bgPrimary container background#0F1115
--nsdk-color-surfaceCard/panel background#171A21
--nsdk-color-textMain text color#F5F7FA
--nsdk-color-mutedSecondary text color#9AA4B2
--nsdk-font-familyUI font family'Satoshi', 'Inter', sans-serif

​
Example: host-level CSS override

:root {
  --nsdk-color-primary: #0a7cff;
  --nsdk-color-bg: #f8fafc;
  --nsdk-color-surface: #ffffff;
  --nsdk-color-text: #0f172a;
  --nsdk-color-muted: #475569;
  --nsdk-font-family: "Satoshi", "Inter", sans-serif;
}

​
Example: boot-time theme object

NSDK('boot', {
  widgets: [{ type: 'insights' }],
  mount: '#nsdk-container',
  embedToken: '<EMBED_TOKEN>',
  theme: {
    colors: {
      primary: '#0a7cff',
      background: '#f8fafc',
      surface: '#ffffff',
      text: '#0f172a',
      muted: '#475569'
    },
    typography: {
      fontFamily: 'Satoshi, Inter, sans-serif'
    }
  }
})
Prefer keeping color and font tokens in your existing design-system variables, then map those values into NSDK theme tokens. This keeps tenant UI and embedded UI consistent.
ScenarioMinimum required configurationRecommended additions
First declarative embedNSDK_BASE_URL, container with data-nsdk="true", data-nsdk-widget, data-nsdk-tokenSame-origin token route, HTTPS-only deployment, short token TTL
Imperative app-controlled embedNSDK_BASE_URL, NSDK('boot'), widgets, mount, embedTokenExplicit cleanup with NSDK('destroy') on page transitions
Production tenant deploymentAll frontend and backend values aboveSecret manager for Connected App secret, replay-safe jti, server clock sync, CSP / origin controls, shared UI theme tokens

​
Validation checklist

Verify iss, aud, iat, exp, and jti first. The most common issues are wrong audience, wrong time unit, or signing with a secret that does not match the Connected App.
Confirm NSDK_BASE_URL points to the hosted SDK origin, nsdk-loader.js loads successfully, and the mount selector or data-nsdk container exists before boot.
Check that your embed-token endpoint is same-origin or explicitly configured for CORS with credentials and authenticated tenant sessions.