Tenant embedding guide

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

Frontend host page

A page in your tenant application where you can load the SDK script and render a mount container.

Backend token route

A backend endpoint that can mint short-lived Embed Tokens for the currently authenticated tenant user.

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.

For the end-to-end embedded integration path, use SDK integration.
For Azure AD OIDC sign-in or request-level API token handling, use Authentication guide.
For token lifecycle and auth pattern comparison, use Authentication.

Required configuration

Value	Where it is used	Why it matters
`NSDK_BASE_URL`	Tenant frontend	Loads `nsdk-loader.js` from the hosted SDK origin.
`NSDK_CONNECTED_APP_CLIENT_ID`	Tenant backend	Used as JWT `iss` when minting the Embed Token.
`NSDK_CONNECTED_APP_SECRET_KEY`	Tenant backend only	Signs the Embed Token with HS256.

The full field-level reference for these values lives in Configuration reference.

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>

Add a widget container

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

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

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

When should the frontend fetch the Embed Token?

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.

Should you use declarative or imperative boot?

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.

How long should the Embed Token live?

Keep it short-lived. The current guidance is 5-15 minutes, with iat and exp expressed in Unix seconds.

What makes a token valid?

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.

No browser signing

Never expose the Connected App secret or JWT signing logic to frontend code.

Short-lived token handoff

Do not store Embed Tokens in browser local storage. Treat them as short-lived bootstrap credentials.

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

The SDK script loads but the widget does not render

The token endpoint works but NSDK rejects the token

Recheck iss, aud, iat, exp, and the HS256 signing secret. Audience mismatches and milliseconds-vs-seconds timestamps are the most common causes.

The frontend cannot fetch the token route

Prefer a same-origin token endpoint. If that is not possible, configure CORS explicitly for the tenant frontend origin and any required credentials flow.

Need the full parameter reference

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.

Getting Started

Support & Troubleshooting

Architecture & Security

What you need before you embed

Frontend host page

Backend token route

Connected App setup

Scope of this guide

Required configuration

Runtime decisions

Minimal implementation flow

Security checklist

No browser signing

Short-lived token handoff

Transport and access controls

Optional imperative mode

Validation and troubleshooting

​What you need before you embed

Frontend host page

Backend token route

Connected App setup

​Scope of this guide

​Required configuration

​Runtime decisions

​Minimal implementation flow

​Security checklist

No browser signing

Short-lived token handoff

Transport and access controls

​Optional imperative mode

​Validation and troubleshooting

What you need before you embed

Scope of this guide

Required configuration

Runtime decisions

Minimal implementation flow

Security checklist

Optional imperative mode

Validation and troubleshooting