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

# Authentication

> Authentication overview, integration patterns, and token lifecycle guidance for Narrative SDK v1.5.

<Info>
  Use this page to choose the right authentication pattern before implementation. For embedded runtime setup, use [SDK integration](/sdk/integration) and [Tenant embedding guide](/sdk/tenant-embedding-guide). For request-level API handling, use [Authentication guide](/sdk/api-auth).
</Info>

## Authentication patterns at a glance

<Columns cols={3}>
  <Card title="Embedded auth" 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">
    Use this when Narrative SDK runs inside your application shell and your backend mints a short-lived Embed Token for the current tenant user.
  </Card>

  <Card title="Azure OIDC auth" 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">
    Use this when a user signs in through the configured Azure AD OIDC flow and the platform establishes a session after the identity provider callback completes.
  </Card>

  <Card title="API auth" icon="https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/server.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=4a767cfdcb6585e74810e5c286495132" width="64" height="64" data-path="SVG/server.svg">
    Use this when your application calls protected Narrative SDK APIs after a user session has already been established through embedded or Azure OIDC auth.
  </Card>
</Columns>

## Pattern selection guide

| Pattern         | When to use it                                           | Who issues the first credential                                                                 | Primary reference                     |
| --------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------- |
| Embedded auth   | You embed SDK UI into a tenant-owned page or iframe.     | Tenant backend                                                                                  | [SDK integration](/sdk/integration)   |
| Azure OIDC auth | User signs in through the configured Azure AD OIDC flow. | Azure AD OIDC + Narrative SDK platform                                                          | [Authentication guide](/sdk/api-auth) |
| API auth        | Your app makes protected API requests after sign-in.     | Narrative-issued internal access token obtained through embedded exchange or Azure OIDC sign-in | [Authentication guide](/sdk/api-auth) |

## Shared security expectations

<Warning>
  Keep long-lived secrets server-side only, use HTTPS end-to-end, and fail closed whenever token validation or refresh cannot be completed safely.
</Warning>

<Columns cols={3}>
  <Card title="Server-side trust boundary" 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">
    Never expose Connected App secrets, refresh secrets, or signing keys in browser code.
  </Card>

  <Card title="Short-lived access" icon="https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/timer.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=218100a8011939edb626ef3480a13724" width="64" height="64" data-path="SVG/timer.svg">
    Treat access credentials as short-lived and refresh them through an authenticated backend or platform-managed flow.
  </Card>

  <Card title="Tenant scope verification" icon="https://mintcdn.com/narrative-b13c445c/qi6sqKB_OLTe8ty2/SVG/server.svg?fit=max&auto=format&n=qi6sqKB_OLTe8ty2&q=85&s=4a767cfdcb6585e74810e5c286495132" width="64" height="64" data-path="SVG/server.svg">
    Confirm tenant and user scope during bootstrap, refresh, and high-risk transitions.
  </Card>
</Columns>

## Pattern details

<AccordionGroup>
  <Accordion title="Embedded auth: tenant-signed bootstrap for embedded UI">
    Embedded auth is the standard choice when Narrative SDK is rendered inside a tenant application. The tenant backend validates the existing tenant user session, mints a short-lived Embed Token, and passes that token to the embedded runtime during boot. Narrative SDK verifies the token and establishes a tenant-scoped runtime session.
  </Accordion>

  <Accordion title="Azure OIDC auth: sign-in through the configured Azure AD flow">
    Azure OIDC auth applies when a user signs in through the configured Azure AD OIDC flow instead of receiving an Embed Token from a tenant shell. The platform redirects the user to Azure AD, receives the callback with identity claims, and then establishes the Narrative SDK session. This is the current non-embedded sign-in path supported by the platform.
  </Accordion>

  <Accordion title="API auth: protected requests after session establishment">
    API auth applies after a valid user session already exists, whether established through embedded token exchange or Azure OIDC sign-in. Protected Narrative SDK APIs require a Narrative-issued internal access token, not a raw identity-provider token. The backend also validates tenant and user binding before allowing access.
  </Accordion>
</AccordionGroup>

## Token lifecycle

The same lifecycle concepts apply across embedded, Azure OIDC, and API auth, even though the first credential is issued differently in each mode.

### 1. Acquisition

| Mode            | Acquisition summary                                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Embedded auth   | Tenant backend mints a short-lived Embed Token for the current tenant user after validating the local user session.                                |
| Azure OIDC auth | User completes sign-in through the configured Azure AD OIDC flow; the platform receives the identity callback and establishes the initial session. |
| API auth        | Client or backend receives a Narrative-issued internal access token after a successful embedded token exchange or Azure OIDC sign-in.              |

### 2. Active use

* Use the acquired credential only for the session and scope it was issued for.
* Keep access tokens in a controlled runtime store. The current web client uses persisted state management for access and refresh tokens; if your integration does the same, ensure the store is not exposed to untrusted code.
* Re-check user and tenant scope before calling sensitive capabilities.

### 3. Refresh

* Refresh should happen only after the caller detects a genuine expiry or explicit authentication failure.
* Attempt a bounded refresh once, then retry the protected call once.
* If refresh fails, clear local auth state and require the user to sign in again.

### 4. Expiry

* Embed Tokens are bootstrap credentials and should remain short-lived.
* Access tokens should also remain short-lived and be replaced through the approved refresh path.
* Do not continue retrying expired tokens after the platform signals that the credential is no longer valid.

### 5. Error handling

Current API handling should follow a single-refresh policy rather than relying on fine-grained `401` classifications from the backend.

| Condition                                                      | Expected handling                                                                                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Any protected request returns `401 Unauthorized`               | Attempt one controlled refresh, then retry once.                                                                                      |
| Retry still returns `401 Unauthorized`                         | Fail closed, clear session state, and return the user to sign-in.                                                                     |
| Invalid signature, malformed token, or tenant/context mismatch | Treat as authentication failure and re-establish the correct session instead of assuming the server will expose a stable subcategory. |

## Embedded auth contract

Narrative embedded auth uses a token-exchange pattern:

```mermaid theme={null}
sequenceDiagram
  participant TenantBackend as Tenant backend
  participant TenantFrontend as Embedded frontend
  participant NSDK as NSDK platform

  TenantBackend->>TenantFrontend: Embed Token (tenant-signed JWT)
  TenantFrontend->>NSDK: Present Embed Token during SDK bootstrap
  NSDK->>NSDK: Verify signature and claims
  NSDK-->>TenantFrontend: Tenant-scoped runtime session
```

### Embed Token requirements

| Field                                | Requirement                      | Notes                                                                                                              |
| ------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| JWT standard                         | RFC 7519                         | Use a normal JWT envelope.                                                                                         |
| Algorithm                            | `HS256`                          | Must match connected app secret configuration.                                                                     |
| `aud`                                | `nsdk-embed`                     | Required exactly as shown.                                                                                         |
| `exp`                                | 5-15 minute lifetime recommended | Keep the embed token short-lived.                                                                                  |
| `iss`                                | Connected app client id          | Identifies issuing tenant backend.                                                                                 |
| `sub`                                | Tenant user identifier           | Stable user identifier in tenant scope.                                                                            |
| `jti`                                | Unique token id                  | Supports uniqueness and replay controls.                                                                           |
| `nsdk.user.name` / `nsdk.user.email` | Recommended                      | Provides user identity context for the embedded session. Omitting these fields may limit personalisation features. |

## What to read next

* Use [SDK integration](/sdk/integration) for the end-to-end embedded integration path.
* Use [Tenant embedding guide](/sdk/tenant-embedding-guide) for embedded runtime decisions and boot options.
* Use [Authentication guide](/sdk/api-auth) for Azure OIDC and API auth request handling, refresh, and sign-out behaviour.