Expand OAuth 2.0 PKCE tutorial metadata, summary, and FAQ

[basit3407]

Summary

This PR expands the OAuth 2.0 getting-started tutorial for Quran Foundation User APIs so it is easier to discover, quicker to skim, and more self-serve for developers integrating PKCE-based authentication.

What Changed

• added SEO-oriented frontmatter metadata to the OAuth 2.0 tutorial
• added a top-level quick summary block covering audience, prerequisites, expected time, and outcome
• added a new FAQ section covering common integration questions
• documented the recommended default scope set and clarified scope usage
• clarified access token lifetime and refresh token expectations
• clarified that pre-production and production tokens are not interchangeable
• explained the difference between public and confidential clients and reinforced the default confidential-client assumption
• documented the required x-auth-token and x-client-id request headers in a single reference point
• added troubleshooting guidance for invalid_client
• added guidance on linking Quran Foundation users to application data via the sub claim

Why

The existing tutorial already explained the PKCE flow well, but it was missing several high-value pieces of developer-facing context:

• search/discovery metadata for external indexing
• a concise summary for readers landing on the page cold
• answers to the most common implementation and environment questions

This update makes the page more useful as both an onboarding guide and a durable reference for teams implementing Quran Foundation User API authentication.

User Impact

Developers should be able to:

• find the tutorial more easily through search
• understand faster whether the guide applies to their integration
• avoid common mistakes around environment mismatch, client type, token refresh, and required headers
• map authenticated Quran Foundation users to their own application records with less guesswork

Root Cause

The tutorial content was strong on the step-by-step flow, but thin on search metadata and recurring operational questions that developers typically need after the first read-through.

Validation

• ran yarn build
• confirmed the docs site builds successfully with the updated tutorial content

Notes

This is a docs-only change. No API behavior or runtime code paths were modified.

[cloudflare-workers-and-pages]

Deploying qf-api-docs with    Cloudflare Pages

Latest commit:	de29988
Status:	✅  Deploy successful!
Preview URL:	https://e53a0cb7.qf-api-docs.pages.dev
Branch Preview URL:	https://seo-geo-priority1-fixes.qf-api-docs.pages.dev

View logs

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b456cf7d50

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[basit3407]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR enhances the OAuth 2.0 (Authorization Code + PKCE) getting-started tutorial to be more discoverable and self-serve for developers integrating Quran Foundation User APIs.

Changes:

• Added SEO-focused frontmatter metadata (title/description/keywords) and a “Quick Summary” info block near the top.
• Added additional scope clarification near the “headers” section to reduce confusion about which endpoints require which scopes.
• Added a new FAQ section covering scopes, token lifetime/refresh, environment isolation, client types, required headers, troubleshooting invalid_client, and mapping users via sub.

---

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