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.

Use this page for the end-to-end embedded implementation path. For authentication pattern selection across embedded, standalone, and API auth, use Authentication. For field-by-field parameter definitions, use Configuration reference. For embed-runtime decisions, use Tenant embedding guide.

​
Integration handoff map

https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/lock.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=be29c8f389110e9dd5032501c0e8f00b

Tenant backend

Holds the Connected App secret, validates the tenant user session, and mints the short-lived Embed Token.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/frontend-shell.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=13c676d362a2a3a7a60bfa0fae245ad6

Tenant frontend

Loads the SDK script, renders the container, fetches the Embed Token, and hands it to the runtime.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/server.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=4a767cfdcb6585e74810e5c286495132

Narrative SDK

Verifies the token exchange and boots the embedded product surface with tenant-scoped session state.

​
Prerequisites

RequirementWhy you need itDetailed reference
Connected App provisioned in Narrative SDKSupplies the client id and secret used for Embed Token signing.Configuration reference
Backend token endpoint in the tenant appMints short-lived Embed Tokens for the current tenant user.Tenant embedding guide
Frontend host page or mount targetGives the SDK a place to render the embedded experience.Configuration reference
Never mint Embed Tokens in frontend code. Keep the signing secret in your backend secret manager only.

​
When to use this page

This page is specific to embedded integration where a tenant backend issues the Embed Token and a tenant-owned frontend hosts the SDK runtime.
1

Load the SDK script

<script>
  (function (w, d, s, u, n) {
    w[n] = w[n] || function () { (w[n].q = w[n].q || []).push(arguments) }
    var js = d.createElement(s); js.async = true; js.src = u
    d.head.appendChild(js)
  })(window, document, 'script', '<NSDK_BASE_URL>/nsdk-loader.js', 'NSDK')
</script>
2

Render a container

<div id="nsdk-container" data-nsdk="true" data-nsdk-widget="insights"></div>
3

Provide the Embed Token

Browser
const { embed_token } = await fetch('/your-embed-token-endpoint').then((r) => r.json())
document.getElementById('nsdk-container')?.setAttribute('data-nsdk-token', embed_token)

​
What happens across the boundary

​
Integration checkpoints

Confirm that <NSDK_BASE_URL>/nsdk-loader.js loads successfully from the tenant frontend before debugging token or render issues.
The token route must run on the tenant backend, validate the current tenant user, and sign the token with the Connected App secret.
In declarative mode, the data-nsdk container must exist before the SDK runtime reads the token and boots the widget.
Only after the widget can boot cleanly should you move on to downstream auth and surface API validation.

​
Delivery checklist

CheckExpected result
Loader script loads from NSDK_BASE_URLBrowser loads nsdk-loader.js with no origin or CSP failures.
Token endpoint returns a fresh Embed TokenResponse includes a short-lived token for the current tenant user.
SDK container rendersEmbedded widget mounts without token or config errors.
Protected APIs succeed after bootAuthenticated requests can reach downstream Coach, Money, or Growth APIs.
Token and secret handling are server-side onlyNo Connected App secret or signing logic appears in frontend code.

​
Common errors and troubleshooting

Use same-origin route, proxy, or explicit CORS with credentials configuration.
Ensure token is signed with the Connected App secret matching iss.
Set aud exactly to nsdk-embed.
Use Unix seconds (not milliseconds) and keep server time synchronized.
Use Configuration reference for the detailed parameter table and Tenant embedding guide for runtime boot choices.
For the complete troubleshooting guide covering all common integration issues, see Troubleshooting. For common questions, see FAQ.