> ## 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.

# Configuration reference

> Detailed reference for frontend, backend, and embed-token configuration used in Narrative SDK integrations.

<Info>
  This page focuses on integration configuration and authentication contract details for published SDK interfaces.
</Info>

<Columns cols={3}>
  <Card title="Frontend runtime" icon="https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/frontend-shell.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=13c676d362a2a3a7a60bfa0fae245ad6" width="64" height="64" data-path="SVG/frontend-shell.svg">
    Base URLs, loader script, mount target, widget selection, and embed-token handoff in the browser.
  </Card>

  <Card title="UI theme customisation" icon="https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/chart-line.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=06f41cec1f394b05dee7a2a65f657297" width="64" height="64" data-path="SVG/chart-line.svg">
    Customise primary colour, text colour, surface backgrounds, and font family to match your product UI.
  </Card>

  <Card title="Backend secrets" icon="https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/lock.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=be29c8f389110e9dd5032501c0e8f00b" width="64" height="64" data-path="SVG/lock.svg">
    Connected App identifiers and signing secrets that must stay on the tenant backend.
  </Card>

  <Card title="Embed token contract" icon="https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/link-handoff.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=710c716f96a2cf04ebe7fa38257b5ea1" width="64" height="64" data-path="SVG/link-handoff.svg">
    JWT claims, TTL guidance, and validation rules required before NSDK can issue scoped session tokens.
  </Card>
</Columns>

## Configuration groups

<AccordionGroup>
  <Accordion title="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.                         |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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. |
  </Accordion>
</AccordionGroup>

## 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

```css theme={null}
: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

```js theme={null}
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'
    }
  }
})
```

<Note>
  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.
</Note>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<Info>
  For the complete troubleshooting guide covering all common integration issues, see [Troubleshooting](/sdk/troubleshooting). For common questions, see [FAQ](/sdk/faq).
</Info>

## Related pages

* [Quickstart](/sdk/quickstart)
* [SDK integration](/sdk/integration)
* [Tenant embedding guide](/sdk/tenant-embedding-guide)
* [Authentication](/sdk/authentication)
* [Capability guide overview](/sdk/api-reference)