Configuration reference

This page focuses on integration configuration and authentication contract details for published SDK interfaces.

Frontend runtime

Base URLs, loader script, mount target, widget selection, and embed-token handoff in the browser.

UI theme customisation

Customise primary colour, text colour, surface backgrounds, and font family to match your product UI.

Backend secrets

Connected App identifiers and signing secrets that must stay on the tenant backend.

Embed token contract

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

Configuration groups

Frontend runtime configuration

Use these values in the tenant frontend when loading the SDK and mounting a widget container.

Parameter	Type	Required	Default	Validation / rule	Description
`NSDK_BASE_URL`	`string`	Yes	None	Must be a valid HTTPS base URL in production.	Hosted Narrative SDK frontend origin used to load `nsdk-loader.js`.
`data-nsdk`	`string` / boolean-like attribute	Yes	None	Set to `true`.	Marks the container as an SDK mount target.
`data-nsdk-widget`	`string`	Yes for declarative mount	No 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-token`	`string`	Yes	None	Must be a valid short-lived Embed Token.	Passes the tenant-signed Embed Token to the SDK container.
`mount`	`string` CSS selector	Yes for imperative boot	None	Selector must resolve to one DOM node.	Imperative alternative to declarative container boot.
`widgets[].type`	`string`	Yes for imperative boot	None	Must match an enabled widget type.	Widget list passed to `NSDK('boot', ...)`.
`embedToken`	`string`	Yes for imperative boot	None	Same validation as `data-nsdk-token`.	Embed token passed through imperative mode.

Backend Connected App configuration

These values belong on the tenant backend only. They are used when minting the Embed Token.

Parameter	Type	Required	Default	Validation / rule	Description
`NSDK_CONNECTED_APP_CLIENT_ID`	`string`	Yes	None	Must match the Connected App provisioned in Narrative SDK.	Used as the JWT `iss` claim when minting Embed Tokens.
`NSDK_CONNECTED_APP_SECRET_KEY`	`string`	Yes	None	Keep server-side only; never expose to browser code.	HS256 signing key used to sign the Embed Token.
`/your-embed-token-endpoint`	HTTP route	Yes	None	Should require an authenticated tenant user session.	Backend endpoint that returns a freshly signed Embed Token to the frontend.

Embed Token claim reference

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 / field	Type	Required	Default	Validation / rule	Description
`iss`	`string`	Yes	None	Must equal `NSDK_CONNECTED_APP_CLIENT_ID`.	Identifies the tenant Connected App issuing the token.
`sub`	`string`	Yes	None	Must be a stable tenant user identifier.	Represents the end user in tenant scope.
`aud`	`string`	Yes	None	Must be exactly `nsdk-embed`.	Audience check for embedded SDK token exchange.
`iat`	`number`	Yes	None	Unix timestamp in seconds.	Issued-at time.
`exp`	`number`	Yes	None	Unix timestamp in seconds; 5-15 minutes recommended.	Expiry time for the embed token.
`jti`	`string`	Yes	None	Should be unique per token.	Unique token id for replay-control and traceability.
`nsdk.user.name`	`string`	Yes	None	Non-empty string.	User display name available to the SDK session.
`nsdk.user.email`	`string`	Yes	None	Should be a valid email address.	User email available to the SDK session.
`nsdk.metadata`	`object`	No	Omitted	Keep small and non-sensitive.	Optional tenant-defined metadata associated with the session.

UI theme customisation

Assume your tenant integration already enables runtime UI theming. You can override colours and typography from the host application.

Recommended theme tokens

Token	Purpose	Example
`--nsdk-color-primary`	Main brand action colour	`#FF5418`
`--nsdk-color-bg`	Primary container background	`#0F1115`
`--nsdk-color-surface`	Card/panel background	`#171A21`
`--nsdk-color-text`	Main text colour	`#F5F7FA`
`--nsdk-color-muted`	Secondary text colour	`#9AA4B2`
`--nsdk-font-family`	UI 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 colour 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.

Recommended configuration sets

Scenario	Minimum required configuration	Recommended additions
First declarative embed	`NSDK_BASE_URL`, container with `data-nsdk="true"`, `data-nsdk-widget`, `data-nsdk-token`	Same-origin token route, HTTPS-only deployment, short token TTL
Imperative app-controlled embed	`NSDK_BASE_URL`, `NSDK('boot')`, `widgets`, `mount`, `embedToken`	Explicit cleanup with `NSDK('destroy')` on page transitions
Production tenant deployment	All frontend and backend values above	Secret manager for Connected App secret, replay-safe `jti`, server clock sync, CSP / origin controls, shared UI theme tokens

Validation checklist

Token is rejected before boot

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.

Container does not render

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.

Frontend can load the SDK but cannot fetch a token

Check that your embed-token endpoint is same-origin or explicitly configured for CORS with credentials and authenticated tenant sessions.

For the complete troubleshooting guide covering all common integration issues, see Troubleshooting. For common questions, see FAQ.

Getting Started

Support & Troubleshooting

Architecture & Security

Frontend runtime

UI theme customisation

Backend secrets

Embed token contract

Configuration groups

UI theme customisation

Recommended theme tokens

Example: host-level CSS override

Example: boot-time theme object

Recommended configuration sets

Validation checklist

Frontend runtime

UI theme customisation

Backend secrets

Embed token contract

​Configuration groups

​UI theme customisation

​Recommended theme tokens

​Example: host-level CSS override

​Example: boot-time theme object

​Recommended configuration sets

​Validation checklist

​Related pages

Configuration groups

UI theme customisation

Recommended theme tokens

Example: host-level CSS override

Example: boot-time theme object

Recommended configuration sets

Validation checklist

Related pages