Quran Foundation User APIs OAuth2 Quickstart

Quick Summary

Audience: Developers adding signed-in Quran.com user features such as bookmarks, collections, notes, reading progress, goals, and preferences. Prerequisites: A client_id from Request Access and at least one registered redirect URI. Recommended flow: Hosted login + PKCE in your app, then backend token exchange and refresh for confidential clients. Outcome: One backend-safe User API call with an OAuth2 access_token.

Use this quickstart after choosing User APIs from the Developer Journey. It gets you to the recommended backend architecture and one successful signed-in User API call.

Use the OAuth2 tutorial when you need the full manual flow, client-type details, token exchange examples, refresh handling, scopes, and troubleshooting.

Production vs Pre-live

Pre-live uses a separate user stack

If you are testing User APIs in pre-live, keep the entire flow in pre-live.

• Use the Pre-live User APIs reference when testing pre-live endpoints.
• Use prelive.quran.com for auth paths and auth-backed user data checks.
• Use prelive.quranreflect.org for Quran Reflect paths and data checks.
• Do not mix production login state, production user data, or production docs with pre-live testing.

Recommended Architecture

Default integration shape

• Let your app or website open the Quran Foundation hosted login screen.
• Generate PKCE, state, and nonce in the app or browser client.
• After login, receive the authorization code at your redirect URI.
• Send code + code_verifier + redirect_uri to your backend.
• Keep QF_CLIENT_SECRET on the backend and perform /oauth2/token exchange and refresh there.
• Have your backend or serverless proxy call User APIs with x-auth-token and x-client-id.

Most Request Access clients are confidential clients by default. Direct browser calls from third-party origins are not the recommended web pattern and may be rejected by CORS or origin allowlist checks.

Public-client exception

If Quran Foundation explicitly confirms that your client is public, you can complete token exchange and refresh in the app with PKCE only. If you did not receive that confirmation, assume your client is confidential.

First SDK Request

Once your backend has a signed-in user session, the SDK can call User APIs from server code:

import { createServerClient } from "@quranjs/api/server";

const serverClient = createServerClient({
  clientId: process.env.QF_CLIENT_ID!,
  clientSecret: process.env.QF_CLIENT_SECRET!,
  userSession: {
    accessToken: session.accessToken,
    refreshToken: session.refreshToken,
    expiresAt: session.expiresAt,
  },
});

const bookmarks = await serverClient.auth.v1.bookmarks.list({ first: 10 });

In production, add SDK storage so refreshed user sessions are persisted in your server-side session store. Continue with the JavaScript SDK guide for installation, runtime configuration, and endpoint-specific SDK examples.

First Raw HTTP Request

Raw HTTP works too. Once your backend has an access_token, it can call a User API endpoint like this:

const accessToken = session.accessToken; // OAuth2 access token stored server-side

const response = await fetch(
  "https://apis.quran.foundation/auth/v1/bookmarks",
  {
    headers: {
      "x-auth-token": accessToken,
      "x-client-id": process.env.QF_CLIENT_ID,
    },
  }
);

const bookmarks = await response.json();

For web apps, SDK or raw HTTP requests are usually made by your backend or serverless proxy, not by page JavaScript. Cookies are for your app's own session; x-auth-token and x-client-id are the headers your server sends to Quran Foundation.

Platform Guides

Platform	Recommended pattern	Start here
Web	Server-side session or backend token exchange	Web integration example
React Native	Hosted login + PKCE in the app, backend token exchange	React Native guide
Android	Hosted login + PKCE in the app, backend token exchange	Android guide
iOS	Hosted login + PKCE in the app, backend token exchange	iOS guide
Full OAuth2 and OIDC details	Step-by-step flow, validation, refresh, scopes, and troubleshooting	OAuth2 tutorial

Scope And Token Details

Request only the scopes your app needs. Start with openid for identity, add offline_access when you need refresh tokens, then add feature scopes such as bookmark, collection, note, reading_session, preference, goal, or streak as needed.

Use these references for the details:

• OAuth2 Scopes for available scopes.
• OAuth2 tutorial for token exchange, refresh, state, nonce, and troubleshooting.
• OpenID Connect guide for id_token claims and identity concepts.

Next Steps

• JavaScript SDK guide if you want typed SDK clients in an existing JS/TS backend.
• OAuth2 tutorial for the full Authorization Code with PKCE flow.
• Web integration example for a working server-side implementation.
• User APIs reference for endpoint-by-endpoint API details.

Need Help?

Email [email protected] if you need OAuth2 credentials, redirect URI setup help, or clarification about whether your client is confidential or public.