Skip to main content

Frequently Asked Questions

This FAQ answers common questions developers have when working with Quran Foundation APIs.

Why should I block automatic translation on Quran text returned by the API?​

The API already delivers peer-reviewed translations. Auto-translating them can distort meaning and create theological inaccuracies. Disable auto-translation using the HTML/CSP techniques linked in the Content APIs Quickstart Guide.

How do I obtain OAuth2 credentials?​

Create an app in the Developer Console to receive your client_id. Choosing Backend/server app also gives you a one-time client_secret; a Frontend or mobile app uses PKCE without a secret. These credentials let you request authorization tokens for accessing user data.

What is the difference between Content APIs and User-related APIs?​

Content APIs provide read-only access to Quran data such as chapters, verses, recitations and translations. User-related APIs manage data tied to a specific Quran Foundation account like bookmarks and notes.

How do I use x-auth-token and x-client-id headers?​

Include your OAuth2 access token in the x-auth-token header and your client ID in the x-client-id header when calling authenticated endpoints.

For web apps, the recommended pattern is to store the user session in your backend or secure httpOnly cookies and have your backend or serverless proxy send x-auth-token and x-client-id to Quran Foundation.

Why does the same request work in curl but fail in the browser?​

curl usually sends no browser Origin header, while browser JavaScript does. If you call a User API directly from page code on a third-party origin, the request can be rejected by the target service's browser-origin policy even when the token itself is valid.

For confidential web integrations, route the resource request through your backend or serverless proxy instead of calling Quran Foundation directly from the page.

What are the best practices for refresh tokens?​

Store refresh tokens securely and reuse them until they expire. Refresh tokens allow you to obtain new access tokens without asking the user to re-authorize.

Can I use the demo credentials quran-demo/secret in production?​

No. These demo credentials are for testing only and should not be used in production applications.

How do I redirect users back to my app after logout?​

Include the post_logout_redirect_uri parameter when calling the logout endpoint and pass id_token_hint (the ID token from the login response). The redirect URI must be pre-registered in your OAuth2 client's post_logout_redirect_uris configuration. If post_logout_redirect_uri is set without id_token_hint, the logout request will be rejected.

See Logout with Redirect for implementation examples.

How do I display my app's logo on the consent page?​

Your logo is displayed automatically if logo_uri is configured in your OAuth2 client registration. See Client Configuration for details on setting up your client metadata.

Can I use QF Content in a commercial or freemium app?​

Yes. A Developer may charge for an Application, offer subscriptions or in-app purchases, display advertising, accept donations, or use a freemium model without a separate commercial license, provided that:

  • QF Content is displayed only as part of the Application’s end-user experience;
  • QF Content and raw API data are not sold, sublicensed, or redistributed; and
  • the Application complies with the Developer Terms and any source-specific license requirements.

A Developer must obtain a signed commercial license before selling, sublicensing, or redistributing QF Content or raw API data—for example, as a dataset, data feed, API, content package, or other separately distributed product.

How long can I cache or store QF Content?​

Do not cache or store QF Content for more than 1 week unless QF has expressly permitted longer storage, or the content is available through the Content Sync APIs. If you use the Content Sync exception, perform a next sync at least every 7 days and apply all available changes.

Can I use Content Sync for Quran text or word-by-word data?​

Content Sync supports approved public Quran layouts through mushafs, as well as translations, word_by_word_translations, word_by_word_transliterations, tafsirs, recitations, chapter_recitations, and articles. The word-by-word translation and transliteration groups are separate; transliteration rows use the word_transliteration record type. Chapter-recitation resources are keyed by Audio::Recitation.id and contain chapter audio file rows; the legacy recitations group remains keyed by ayah-recitation IDs and may also receive compatible chapter-file mutations. Mushaf snapshots include metadata, page mappings, and positioned words; font files and images are not included. Use the relevant regular content endpoint for unsupported Quran text variants and other data. Unless QF expressly permits longer storage, the Developer Terms' one-week storage limit still applies to content that is not available through Content Sync.

The Developer Terms reserve all rights not expressly granted. For Connected Apps, display attribution wherever Quranic content is surfaced: “Quran data provided by Quran Foundation.” Also credit translations, tafsir editions, and recitations by their named source or edition within their licensing terms. See Content and attribution requirements and the Developer Terms.

How do I get help with licensing, attribution, or a policy question?​

Email [email protected] with your app, the content or API data involved, your intended use, storage or sync approach, attribution, and any commercial distribution details. Report actual or suspected unauthorised API-related access, security breach, or data exposure within 24 hours. Do not include client secrets or access tokens.