Skip to content

docs: Revamp OAuth 2.0 guide with PKCE flow, examples, and troubleshooting#21

Merged
osamasayed merged 1 commit intomainfrom
getting-started-with-oauth2
Sep 23, 2025
Merged

docs: Revamp OAuth 2.0 guide with PKCE flow, examples, and troubleshooting#21
osamasayed merged 1 commit intomainfrom
getting-started-with-oauth2

Conversation

@basit3407
Copy link
Copy Markdown
Collaborator

@basit3407 basit3407 commented Sep 15, 2025

Summary

This PR fully rewrites the OAuth 2.0 documentation for Quran.Foundation APIs to be clearer, developer-friendly, and aligned with our Quick Start style.
The new guide emphasizes Authorization Code + PKCE for User APIs, while distinguishing it from Client Credentials for Content APIs.

Key changes

  • Reorganized guide into 5 clear steps (client credentials → build auth URL → token exchange → API call → refresh).
  • Added ready-to-run code examples:
    • Node.js (axios) + Python (requests)
    • PKCE helper snippets for generating code_verifier/code_challenge
  • Included example cURL commands for confidential and public clients.
  • Added sample token response and guidance on scope verification.
  • Clarified environment base URLs (Pre-Production vs Production).
  • Documented important considerations: redirect URI matching, state/nonce, scope usage, token storage, PKCE rules.
  • Added a troubleshooting section with common errors and resolutions.

Motivation

The old guide was abstract and difficult to follow. This version:

  • Uses a step-by-step format with concrete code.
  • Reduces developer friction by providing drop-in snippets.
  • Prevents common pitfalls by documenting known issues upfront.
@basit3407
docs: rewrite OAuth 2.0 guide with PKCE flow,
96159a1 
examples, and troubleshooting

- Replaced old high-level OAuth 2.0 overview with step-by-step Authorization Code + PKCE flow.
- Added clear separation between Content API (Client Credentials) and User API (Auth Code).
- Included ready-to-run examples in Python (requests) and Node.js (axios).
- Documented PKCE helper utilities (Node, Python).
- Added example authorization URL, token exchange (public vs confidential), and refresh token flows.
- Clarified required headers for User API calls (x-auth-token, x-client-id).
- Added environment base URLs for Pre-Production vs Production.
- Documented important considerations (redirect URI matching, state/nonce usage, scope usage).
- Added common issues & troubleshooting table.
@vercel
Copy link
Copy Markdown

vercel Bot commented Sep 15, 2025 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
qf-api-docs Ready Ready Preview Comment Sep 15, 2025 5:26am
@osamasayed osamasayed merged commit 2da0b7a into main Sep 23, 2025
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants

@basit3407 @osamasayed