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 embedded runtime implementation details after you choose embedded auth as your integration pattern. For authentication pattern selection across embedded, standalone, and API auth, use Authentication. For parameter-by-parameter definitions, defaults, and validation rules, use Configuration reference.
Need brand alignment? Use Configuration reference to customise font and theme colours from your host app.

​
What you need before you embed

https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/frontend-shell.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=13c676d362a2a3a7a60bfa0fae245ad6

Frontend host page

A page in your tenant application where you can load the SDK script and render a mount container.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/lock.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=be29c8f389110e9dd5032501c0e8f00b

Backend token route

A backend endpoint that can mint short-lived Embed Tokens for the currently authenticated tenant user.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/link-handoff.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=710c716f96a2cf04ebe7fa38257b5ea1

Connected App setup

A provisioned Connected App with a client id and secret that match the token-signing configuration on your backend.

​
Scope of this guide

This guide only covers embedded Narrative SDK boot and runtime decisions.

​
Required configuration

ValueWhere it is usedWhy it matters
NSDK_BASE_URLTenant frontendLoads nsdk-loader.js from the hosted SDK origin.
NSDK_CONNECTED_APP_CLIENT_IDTenant backendUsed as JWT iss when minting the Embed Token.
NSDK_CONNECTED_APP_SECRET_KEYTenant backend onlySigns the Embed Token with HS256.
The full field-level reference for these values lives in Configuration reference.
1

Load the SDK loader

Loader 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

Add a widget container

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

Fetch and set Embed Token

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

​
Runtime decisions

Fetch it only after the tenant app has already established its own authenticated user session. The Embed Token should represent the current tenant user, not an anonymous browser session.
Use declarative boot when you have a stable host page and container. Use imperative boot when your application needs to control mount timing, page transitions, or cleanup explicitly.
Keep it short-lived. The current guidance is 5-15 minutes, with iat and exp expressed in Unix seconds.
It must be JWT + HS256, use aud = nsdk-embed, include the required claims (iss, sub, aud, iat, exp, jti), and include nsdk.user.name plus nsdk.user.email.

​
Minimal implementation flow

​
Security checklist

Keep connected app secrets server-side only. Do not expose token signing logic in browser code.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/lock.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=be29c8f389110e9dd5032501c0e8f00b

No browser signing

Never expose the Connected App secret or JWT signing logic to frontend code.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/timer.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=218100a8011939edb626ef3480a13724

Short-lived token handoff

Do not store Embed Tokens in browser local storage. Treat them as short-lived bootstrap credentials.
https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/server.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=4a767cfdcb6585e74810e5c286495132

Transport and access controls

Use HTTPS, strict origin or CSP controls, and validate tenant user authorisation before minting each token.

​
Optional imperative mode

Browser
NSDK('boot', {
  widgets: [{ type: 'insights' }],
  mount: '#nsdk-container',
  embedToken: '<EMBED_TOKEN>'
})

NSDK('destroy')

​
Validation and troubleshooting

Check that the container exists before boot, data-nsdk="true" is present for declarative mode, and the token has been set on the container before the SDK initializes.
Recheck iss, aud, iat, exp, and the HS256 signing secret. Audience mismatches and milliseconds-vs-seconds timestamps are the most common causes.
Prefer a same-origin token endpoint. If that is not possible, configure CORS explicitly for the tenant frontend origin and any required credentials flow.
Use Configuration reference for field-by-field definitions and Authentication for token and session lifecycle behaviour.
For the complete troubleshooting guide covering all common integration issues, see Troubleshooting. For common questions, see FAQ.