SDK integration

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

Tenant backend

Holds the Connected App secret, validates the tenant user session, and mints the short-lived Embed Token.

Tenant frontend

Loads the SDK script, renders the container, fetches the Embed Token, and hands it to the runtime.

Narrative SDK

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

Prerequisites

Requirement	Why you need it	Detailed reference
Connected App provisioned in Narrative SDK	Supplies the client id and secret used for Embed Token signing.	Configuration reference
Backend token endpoint in the tenant app	Mints short-lived Embed Tokens for the current tenant user.	Tenant embedding guide
Frontend host page or mount target	Gives 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.

If your user signs in through the Azure AD OIDC flow instead of receiving an Embed Token, start with Authentication and Authentication guide instead.
If you need request-level handling for access tokens, refresh, and sign-out, use Authentication guide.

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>

Render a container

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

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

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

1. Loader script is reachable

Confirm that <NSDK_BASE_URL>/nsdk-loader.js loads successfully from the tenant frontend before debugging token or render issues.

2. Token endpoint is authenticated and server-side only

The token route must run on the tenant backend, validate the current tenant user, and sign the token with the Connected App secret.

3. Container exists before token handoff

In declarative mode, the data-nsdk container must exist before the SDK runtime reads the token and boots the widget.

4. Token exchange succeeds before API-level testing

Only after the widget can boot cleanly should you move on to downstream auth and surface API validation.

Delivery checklist

Check	Expected result
Loader script loads from `NSDK_BASE_URL`	Browser loads `nsdk-loader.js` with no origin or CSP failures.
Token endpoint returns a fresh Embed Token	Response includes a short-lived token for the current tenant user.
SDK container renders	Embedded widget mounts without token or config errors.
Protected APIs succeed after boot	Authenticated requests can reach downstream Coach, Money, or Growth APIs.
Token and secret handling are server-side only	No Connected App secret or signing logic appears in frontend code.

Common errors and troubleshooting

CORS blocks token endpoint

Use same-origin route, proxy, or explicit CORS with credentials configuration.

Invalid signature

Ensure token is signed with the Connected App secret matching iss.

Invalid audience

Set aud exactly to nsdk-embed.

Clock skew or wrong time unit

Use Unix seconds (not milliseconds) and keep server time synchronized.

Need exact claim, field, or boot parameter definitions

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.

Getting Started

Support & Troubleshooting

Architecture & Security

Integration handoff map

Tenant backend

Tenant frontend

Narrative SDK

Prerequisites

When to use this page

What happens across the boundary

Integration checkpoints

Delivery checklist

Common errors and troubleshooting

​Integration handoff map

Tenant backend

Tenant frontend

Narrative SDK

​Prerequisites

​When to use this page

​What happens across the boundary

​Integration checkpoints

​Delivery checklist

​Common errors and troubleshooting

Integration handoff map

Prerequisites

When to use this page

What happens across the boundary

Integration checkpoints

Delivery checklist

Common errors and troubleshooting