Use this page for request-level auth handling after you choose an authentication pattern. For the high-level comparison of embedded, Azure OIDC, and API auth, use Authentication.
Supported implementation paths
What’s new in v1.9.0
Settings lists active sign-in sessions and lets users end one other session or all other sessions. A normal logout ends only the current session. An ended session must sign in again to access the workspace. Users must sign in again after upgrading. Partner integrations that manage Narrative user accounts or branding need an update for v1.9.0. See the v1.9.0 release notes for upgrade requirements.What’s new in v1.8.3
v1.8.3 makes sign-out recovery more reliable.
- Explicit sign-out clears the intended session state, and browser refresh keeps the user signed out after logout.
Recommended flow
1
Establish sign-in context
Complete the Azure OIDC sign-in flow or embedded token exchange and confirm that the returned session belongs to the expected tenant user.
2
Store only active access state
Keep short-lived access credentials in a controlled runtime store. The current web client persists access and refresh tokens through state storage; if your integration does the same, ensure the store is not exposed to untrusted code. Do not store long-lived secrets in browser local storage.
3
Call protected capabilities
Attach the active Narrative-issued internal access token to protected runtime requests and keep tenant scope checks close to the request boundary.
4
Handle expiry with one bounded refresh
If the platform returns
401 Unauthorized, request a fresh access token once and retry the failed request once.5
Sign out and clear state
Revoke the current application session, clear client auth state and require sign-in before the next protected action. Preserve other independent sessions.
Azure OIDC auth flow
Azure OIDC auth applies when the user signs in through the configured Azure AD OIDC flow instead of receiving an Embed Token from a tenant application. This is the current non-embedded sign-in path supported by the platform.Azure OIDC implementation guidance
- Azure AD handles credential collection; the platform receives verified identity claims via the callback.
- Narrative-managed email registration requires explicit Terms of Service and Privacy Policy acknowledgement before a new user can complete registration.
- Treat the returned access credential as short-lived runtime state.
- Re-authenticate if sign-in fails or if refresh cannot restore a valid session.
API request handling
Request pattern
Protected Narrative SDK APIs accept only Narrative-issued internal access tokens. Do not send raw identity-provider access tokens directly to these endpoints.JavaScript
Public identity and ownership
Authentication responses expose NarrativeuserId and tenantId as UUIDv4 strings. Treat them as opaque references from the platform; do not parse them as numbers, invent replacements or reuse an external identity provider’s user identifier as a Narrative reference.
Self-service Chat, Growth, Project, Saved Ideas and Money requests derive the user and tenant from the authenticated session. Caller-supplied userId and tenantId overrides are rejected. Resource identifiers, such as a conversation or Project ID, are separate from the user’s public reference.
Public branding uses the tenant UUID in its query and asset URLs; see White-labeling.
Controlled refresh pattern
JavaScript
Token lifecycle handling
Acquisition
- Start only after a successful embedded token exchange or Azure OIDC sign-in.
- Bind the credential to the expected tenant and user context.
- Do not reuse bootstrap or sign-in artifacts as long-lived API credentials.
Refresh
- Refresh only when a protected request returns
401 Unauthorized. - Attempt a single controlled refresh and a single retry.
- If refresh requires backend participation, keep that logic on the server side.
Expiry
- Expect access tokens to expire regularly.
- Remove expired credentials from runtime state as soon as refresh fails.
- Do not continue retry loops beyond the single refresh attempt.
Sign-out
- Clear persisted and memory-held credentials and any cached auth metadata.
- A successful server logout revokes the current session’s access and refresh capability. Other independent sessions remain active.
- Clearing browser state alone does not prove server revocation succeeded. If logout cannot be confirmed, keep the client signed out and report the failure.
- Force the next protected action through sign-in again.
Active sessions
In Settings, openPrivacy & Security and inspect Active sessions. The list identifies This session and shows browser, operating system and last activity for other sessions. End session ends one other session; End all other sessions keeps only the current one. View all opens longer lists.
All three requests require the current Narrative access token. Use the UUIDv4
sessionId returned by the list. To end the current session, use the normal logout flow; the other-session endpoint does not replace it.
Upgrading from v1.8
Require a fresh application sign-in and replace stored application access and refresh tokens. Adopt the returned public UUIDs in client identity handling and public branding URLs, and remove identity overrides from affected self-service requests. Do not keep retrying retired credentials or substitute a locally signed token.Error handling baseline
Security requirements
- Use HTTPS end-to-end.
- Keep refresh or signing secrets off the browser.
- Keep access tokens scoped to the current user and tenant.
- Do not mask repeated authentication failures with silent retries.