Document backend proxy guidance for web User API calls

[basit3407]

Problem

The docs already documented the OAuth2 flow and the x-auth-token / x-client-id header contract, but they did not make the intended web integration shape explicit enough. A reviewer reading the docs could reasonably infer that once a web app has a valid token, calling User APIs directly from browser JavaScript is the normal path.

That is not the recommended pattern for confidential web clients.

Decision

For web integrations, the guidance should be:

• do login + PKCE in the app
• exchange and refresh tokens on the backend
• keep the app's own web session in backend storage or secure httpOnly cookies
• call Quran Foundation User APIs through the app backend or serverless proxy
• have that backend/proxy send x-auth-token and x-client-id outbound to QF

So the docs need to distinguish clearly between:

• cookies used by the integrator's own website session
• x-auth-token / x-client-id used when calling QF APIs

What changed

• quickstart now recommends backend exchange plus backend or serverless proxy calls for web apps
• full OAuth2 tutorial now shows the backend as the resource caller for confidential web clients
• FAQ now explains the curl works but browser fails case
• web example now makes the server-side session plus outbound header model explicit

Impact

A first-time reader should now understand that:

• x-auth-token is still the QF API contract
• web apps usually should not send it directly from page JavaScript
• their backend or proxy is usually the component that sends those headers to QF

Validation

• yarn gen-all

Notes

• yarn typecheck still fails in this repo because of existing Docusaurus theme alias/type issues unrelated to these MDX edits

[cloudflare-workers-and-pages]

Deploying qf-api-docs with    Cloudflare Pages

Latest commit:	d2ef5e9
Status:	✅  Deploy successful!
Preview URL:	https://153c6f55.qf-api-docs.pages.dev
Branch Preview URL:	https://codex-user-api-origin-clarif.qf-api-docs.pages.dev

View logs

[Copilot]

Pull request overview

This PR updates the OAuth2/User APIs documentation to more clearly recommend a backend (or serverless proxy) pattern for web apps: backend-managed token exchange/refresh, server-side session storage, and server-originated User API calls using x-auth-token + x-client-id.

Changes:

• Update the User APIs quickstart to explicitly recommend backend exchange/refresh + backend/proxy User API calls for web apps.
• Adjust the full OAuth2 tutorial to depict the backend as the resource caller for confidential web clients, and expand troubleshooting guidance for browser-origin restrictions.
• Clarify the recommended session + header model in the FAQ and the web integration example.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
docs/tutorials/oidc/user-apis-quickstart.mdx	Adds explicit recommended web-app architecture guidance and clarifies that backend/proxy typically makes the User API call.
docs/tutorials/oidc/getting-started-with-oauth2.mdx	Updates the mermaid flow to show backend resource calls and adds origin-policy guidance + troubleshooting notes.
docs/tutorials/oidc/example-integration.mdx	Makes the server-side session + outbound header model explicit for the web example.
docs/tutorials/faq.mdx	Adds web guidance on session storage and explains the “curl works, browser fails” origin-policy scenario.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.