Skip to main content
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

​
Shared security expectations

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

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 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 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. Narrative-managed email registration requires new users to acknowledge the Terms of Service and Privacy Policy before registration can continue.
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

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

​
Embedded auth contract

Narrative embedded auth uses a token-exchange pattern:

​
Embed Token requirements