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 to choose the right authentication pattern before implementation. For embedded runtime setup, use SDK integration and Tenant embedding guide. For request-level API handling, use Authentication guide.
Authentication patterns at a glance
Embedded auth
Use this when Narrative SDK runs inside your application shell and your backend mints a short-lived Embed Token for the current tenant user.
Azure OIDC auth
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.
API auth
Use this when your application calls protected Narrative SDK APIs after a user session has already been established through embedded or Azure OIDC auth.
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 |
| Azure OIDC auth | User signs in through the configured Azure AD OIDC flow. | Azure AD OIDC + Narrative SDK platform | Authentication guide |
| 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 |
Shared security expectations
Server-side trust boundary
Never expose Connected App secrets, refresh secrets, or signing keys in browser code.
Short-lived access
Treat access credentials as short-lived and refresh them through an authenticated backend or platform-managed flow.
Tenant scope verification
Confirm tenant and user scope during bootstrap, refresh, and high-risk transitions.
Pattern details
Embedded auth: tenant-signed bootstrap for embedded UI
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.
Azure OIDC auth: sign-in through the configured Azure AD flow
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.
API auth: protected requests after session establishment
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.
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-grained401 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: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 for the end-to-end embedded integration path.
- Use Tenant embedding guide for embedded runtime decisions and boot options.
- Use Authentication guide for Azure OIDC and API auth request handling, refresh, and sign-out behaviour.