Skip to content

user-apis-quickstart.mdx

Latest commit

 

History

History
175 lines (135 loc) · 9.48 KB

user-apis-quickstart.mdx

File metadata and controls

175 lines (135 loc) · 9.48 KB
sidebar_position 0
displayed_sidebar APIsSidebar
title Quran Foundation User APIs OAuth2 Quickstart
description Quickstart for accessing Quran Foundation User APIs with OAuth2 Authorization Code flow, PKCE, OpenID Connect, and a backend token exchange.
keywords
quran foundation oauth2 quickstart
quran foundation user apis
oauth2 authorization code pkce
openid connect quran foundation
bookmarks collections reading progress api
sidebar_label User APIs Quickstart

Quran Foundation User APIs OAuth2 Quickstart

:::info 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

:::important 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.

For web apps, the recommended shape is:

  • keep token exchange and refresh on your backend
  • keep the app's user session in secure server storage or httpOnly cookies
  • have your backend or serverless proxy send x-auth-token and x-client-id when calling Quran Foundation User APIs

Direct browser calls from third-party origins are not the recommended web pattern and may be rejected by CORS allowlisting or other origin allowlist checks.

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.

:::tip 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();

For web apps, this request is typically 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.

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.
  • Calling User APIs directly from browser JavaScript in a confidential web integration instead of routing the request through your backend or proxy.

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

Need Help?

Email developers@quran.com if you need OAuth2 credentials, redirect URI setup help, or clarification about whether your client is confidential or public.