Quran Foundation User APIs OAuth2 Quickstart

Quick Summary

Audience: Developers building signed-in features with Quran Foundation User APIs such as bookmarks, collections, reading progress, goals, and preferences. Prerequisites: A client_id from Request Access and at least one registered redirect URI. Recommended flow: Use the hosted Quran Foundation login page, generate PKCE in your app or browser client, then send the authorization code to your backend for token exchange and refresh. Outcome: Your app can authenticate users, read OpenID Connect identity data from the id_token, and call User APIs with an access_token.

Quran Foundation User APIs use OAuth2 Authorization Code flow with PKCE and OpenID Connect. For most newly issued Request Access clients, the safest default is a confidential-client setup: your app handles the login redirect, but your backend keeps CLIENT_SECRET and exchanges the code for tokens.

Recommended Architecture

Default integration shape

• Let your app or website open the Quran Foundation hosted login screen.
• Generate PKCE 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 CLIENT_SECRET on the backend and perform the /oauth2/token exchange there.
• Refresh tokens on the backend unless Quran Foundation explicitly confirms that your client is public.

This pattern gives you OAuth2 and OpenID Connect without embedding secrets in a mobile app or browser app. It also keeps the integration aligned with how most Request Access clients are provisioned today.

Choose Your Platform

Use the quickstart guidance on this page for the architecture decision, then jump to the guide that matches your stack.

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, client types, validation, and token behavior	OAuth2 tutorial

OAuth2 Flow

For most Quran Foundation User APIs integrations, the end-to-end flow looks like this:

1. Generate PKCE parameters and a cryptographically random OAuth2 state value, and if you rely on id_token for identity, an OIDC nonce, then redirect the user to the Quran Foundation OAuth2 authorization endpoint.
2. Let the user sign in and approve the requested scopes.
3. Receive an authorization code at your registered redirect URI and verify that the returned state exactly matches the value you generated before trusting the callback.
4. Send code + code_verifier + redirect_uri from the client to your backend.
5. Exchange the code on the backend for access_token, refresh_token, and id_token.
6. Use the access_token to call User APIs such as bookmarks, collections, and reading progress.
7. Use the id_token for user identity claims such as sub.
8. Refresh tokens on the backend for confidential clients.

Public-client exception

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

If you use an OAuth2 or OIDC client library, make sure it generates and validates state automatically, and nonce as well when you rely on id_token. Do not disable those checks.

Minimal API Call

Once you have an access_token, you can call a User API endpoint like this:

const accessToken = session.accessToken; // OAuth2 access token returned by your backend

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

const bookmarks = await response.json();

Quick Reference

Common scopes

Request only the scopes your app actually needs.

Scope	Access
openid	OpenID Connect identity claims in the id_token
offline_access	Refresh tokens for long-lived sessions
user	User profile information
bookmark	Bookmarked verses
collection	Saved collections
reading_session	Reading progress and history
preference	User preferences and settings
goal	Reading goals
streak	Reading streaks

Token refresh

• Request offline_access if you need refresh tokens.
• For confidential clients, keep refresh on the backend together with CLIENT_SECRET.
• For public clients, refresh can happen in the app.
• Use the OAuth2 tutorial for deeper token lifetime and validation details.

Common mistakes

• Embedding CLIENT_SECRET in a mobile app or browser app.
• Calling /oauth2/token directly from a confidential client without backend client authentication.
• Skipping OAuth2 state validation, or nonce validation when you rely on id_token.
• Mixing prelive and production OAuth2 environments.
• Requesting more scopes than your app needs.
• Treating the id_token as an API access token instead of using the access_token.

AI Handoff Prompt

Use this prompt when you want an AI coding tool to implement the recommended User APIs flow in your codebase:

Implement Quran Foundation User APIs authentication using the recommended backend-safe OAuth2 Authorization Code with PKCE and OpenID Connect flow.

Requirements
- Open the Quran Foundation hosted login screen from the app or browser client.
- Generate PKCE, OAuth2 state, and OpenID Connect nonce in the client.
- Receive the authorization code at the redirect URI.
- Send code + code_verifier + redirect_uri to the backend.
- Keep CLIENT_SECRET on the backend for confidential clients.
- Exchange the code and refresh tokens on the backend by default.
- Use access_token for User APIs such as bookmarks, collections, reading progress, and preferences.
- Read user identity claims such as sub from the id_token.
- Validate state on callback, and validate nonce when you rely on id_token.
- Only use direct in-app token exchange if Quran Foundation explicitly confirms that the client is public.

Documentation to follow
- Quickstart: https://api-docs.quran.foundation/docs/tutorials/oidc/user-apis-quickstart
- OAuth2 tutorial: https://api-docs.quran.foundation/docs/tutorials/oidc/getting-started-with-oauth2
- Web integration example: https://api-docs.quran.foundation/docs/tutorials/oidc/example-integration
- React Native guide: https://api-docs.quran.foundation/docs/tutorials/oidc/mobile-apps/react-native
- Android guide: https://api-docs.quran.foundation/docs/tutorials/oidc/mobile-apps/android
- iOS guide: https://api-docs.quran.foundation/docs/tutorials/oidc/mobile-apps/iOS
- OpenID Connect guide: https://api-docs.quran.foundation/docs/tutorials/oidc/openid-connect
- User APIs reference: https://api-docs.quran.foundation/docs/category/user-related-apis

Next Steps

• OAuth2 tutorial for the full Authorization Code with PKCE flow, client types, validation, and troubleshooting.
• Web integration example for a working server-side implementation.
• React Native guide for mobile login flow and PKCE setup.
• OpenID Connect guide for id_token claims and identity concepts.
• 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.