[Docs] Clarify direct flow execution is not supported for browser SPA sign-in

[Malith-19]

Purpose

Browser SPAs are public clients that cannot be verified when calling the Flow Execution API directly. The documentation did not make this explicit, and some SDK content presented the embedded (app-native) sign-in pattern as valid for SPAs.

This PR updates the documentation to state clearly that browser SPAs must sign in through the redirect-based OAuth 2.0 authorization_code + PKCE flow and cannot initiate a sign-in flow directly via POST /flow/execute. It also scopes the restriction correctly: it applies to sign-in (authentication) only — registration and recovery have no redirect-based equivalent and continue to run through the Flow Execution API.

Per the docs-first alignment in discussion #2744, the SDK is not hard-blocking or removing the embedded flow method (it is legitimately used by confidential/server-side clients and by the hosted pages for continuation). The enforcement is documentation guidance, so the callouts describe the pattern as unsupported for browser SPAs rather than as a runtime error.

Approach

• SDK overview docs (javascript, browser, react, vue): add callouts steering browser SPAs to the redirect-based sign-in flow, and note that continuing a flow with an executionId (as the hosted pages do) and initiating from confidential/server-side code are unaffected.
• react-vanilla-sample README: add a notice steering browser SPAs to the redirect-based react-sdk-sample.
• Integration Models guide: scope the App-Native SPA warning and the grant-type note to authentication flows, clarifying that registration, recovery, and user onboarding remain directly initiable via the Flow Execution API regardless of grant type.

Related Issues

• Fixes [Docs] Update documentation to clarify that direct flow execution is not supported for browser SPAs #3219
• Fixes Update SDK to remove native SPA flow patterns and redirect developers to authorization_code + PKCE flows #3217 — resolved via the docs-first approach agreed in [Design Discussion] Client verification enhancement for app native flows #2744; the SDK will not hard-block the embedded method, so the documentation guidance is the resolution.

Related PRs

• Block direct HTTP flow initiation for authorization_code grant type apps #3289, Restrict direct flow initiation guard to authentication flows #3395 — backend enforcement of the authentication-flow restriction.
• Move JavaScript SDKs out of the monorepo #3456 — SDK relocation to thunder-id/javascript-sdks.

Checklist

• Followed the contribution guidelines.
• Manual test round performed and verified.
• Documentation provided.
  • Ran Vale and fixed all errors and warnings
• Tests provided.
  • Unit Tests
  • Integration Tests
• Breaking changes.
  • Breaking changes section filled.
  • breaking change label added.

Security checks

• Followed secure coding standards in WSO2 Secure Coding Guidelines.
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

Summary by CodeRabbit

• Documentation
  • Clarified that browser-based SPAs must use the redirect-based OAuth 2.0 authorization code flow with PKCE for sign-in.
  • Added warnings across SDK guides that direct browser sign-in is not supported and may fail at runtime.
  • Explained that continuation requests are still allowed, and registration, recovery, and onboarding flows are not restricted.
  • Updated the React sample README to steer SPA users toward the recommended approach.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation across the key-concepts guide, browser/JavaScript/React/Vue SDK overviews, and a sample README is updated to state that browser SPAs must use redirect-based OAuth2 authorization_code + PKCE, and that direct browser sign-in via the Flow Execution API is unsupported.

Changes

Browser SPA sign-in documentation updates

Layer / File(s)	Summary
Core authentication model restriction clarification docs/content/guides/key-concepts/authentication/integration-models.mdx	Scopes the App-Native SPA restriction to authentication flows and describes Flow Execution API rejection behavior for flowType: AUTHENTICATION initiation without executionId when authorization_code is configured.
SDK overview warnings for browser and framework SDKs docs/content/sdks/browser/overview.mdx, docs/content/sdks/javascript/overview.mdx, docs/content/sdks/react/overview.mdx, docs/content/sdks/vue/overview.mdx	Adds warnings that direct browser sign-in initiation is unsupported and directs SPAs to redirect-based authorization_code + PKCE flows.
Sample README warning samples/apps/react-vanilla-sample/README.md	Adds a warning that the sample’s direct POST /flow/execute sign-in is unsupported for browser SPAs and points to react-sdk-sample.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• thunder-id/thunderid#2798: Updates the react-vanilla-sample around browser SPA sign-in flow guidance.
• thunder-id/thunderid#3319: Implements browser-side /flow/execute app-native flow behavior that these docs now explicitly disallow for SPAs.
• thunder-id/thunderid#3385: Covers the same Flow Execution API restriction for authorization_code apps and authentication-flow initiation.

Suggested reviewers: brionmario, DonOmalVindula, jeradrutnam

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The docs updates align with #3219 by stating browser SPAs must use redirect-based auth and no longer imply direct sign-in is valid.
Out of Scope Changes check	✅ Passed	All documented changes stay within the browser-SPA authentication guidance and sample README scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the main documentation change and stays concise.
Description check	✅ Passed	The description includes Purpose, Approach, Related Issues/PRs, checklist, and security sections, matching the template well.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Bundle Report

Bundle size has no change ✅

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ThaminduDilshan]

Not related to this PR, but related to your effort... IMO we shouldn't provide a sample for a non recommended implementation. Instead we should give a nextJS sample maybe.

@darshanasbg @jeradrutnam @brionmario WDYT?