Skip to main content

πŸš€ Quick Start Guide

Welcome to the Quran Foundation API! This Quick Start guide will help you get up and running within minutes.

Recommended for first-time users

Follow these steps to make your first successful API call.

πŸ“© Step 1: Request API Access​

  1. Visit the Request Access page.
  2. Fill out the form to request your Client ID and Client Secret.
  3. Your credentials will be emailed to you.
danger

⚠️ Do not share your credentials. Keep your client_id and client_secret secure.

πŸ”‘ Step 2: Get Your Access Token (Authentication)​

The Quran Foundation API uses OAuth2 Client Credentials flow. Access tokens are valid for 1 hour (3600 seconds).

Token Request Examples:​

cURL
curl --request POST \
  --url https://prelive-oauth2.quran.foundation/oauth2/token \
  --user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=content'
JavaScript (Node.js)
const axios = require('axios');

async function getAccessToken() {
  const clientId = 'YOUR_CLIENT_ID';
  const clientSecret = 'YOUR_CLIENT_SECRET';

  const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

  try {
    const response = await axios({
      method: 'post',
      url: 'https://prelive-oauth2.quran.foundation/oauth2/token',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      data: 'grant_type=client_credentials&scope=content'
    });

    return response.data.access_token;
  } catch (error) {
    console.error('Error getting access token:', error);
  }
}
Python
import requests

def get_access_token():
    client_id = 'YOUR_CLIENT_ID'
    client_secret = 'YOUR_CLIENT_SECRET'

    response = requests.post(
        'https://prelive-oauth2.quran.foundation/oauth2/token',
        auth=(client_id, client_secret),
        headers={'Content-Type': 'application/x-www-form-urlencoded'},
        data='grant_type=client_credentials&scope=content'
    )

    return response.json()['access_token']

Sample Response:​

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "content"
}
tip

πŸ’‘ Tip: Store this token securely and reuse it until expiration to avoid unnecessary token requests.

🟒 Step 3: Use the Access Token​

Include the token in your API request headers:

x-auth-token: YOUR_ACCESS_TOKEN
x-client-id: YOUR_CLIENT_ID  # Always include your client ID with each request

πŸ“‚ Step 4: Make Your First API Call​

Example: List All Surahs (Chapters)​

cURL
curl --request GET \
  --url https://apis-prelive.quran.foundation/content/api/v4/chapters \
  --header "x-auth-token: YOUR_ACCESS_TOKEN" \
  --header "x-client-id: YOUR_CLIENT_ID"
JavaScript (Node.js)
const axios = require('axios');

async function getChapters(accessToken, clientId) {
  try {
    const response = await axios({
      method: 'get',
      url: 'https://apis-prelive.quran.foundation/content/api/v4/chapters',
      headers: {
        'x-auth-token': accessToken,
        'x-client-id': clientId
      }
    });

    return response.data;
  } catch (error) {
    console.error('Error fetching chapters:', error);
  }
}
Python
import requests

def get_chapters(access_token, client_id):
    response = requests.get(
        'https://apis-prelive.quran.foundation/content/api/v4/chapters',
        headers={
            'x-auth-token': access_token,
            'x-client-id': client_id
        }
    )

    return response.json()

Example Successful Response:​

{
  "chapters": [
    {
      "id": 1,
      "revelation_place": "makka",
      "revelation_order": 5,
      "bismillah_pre": false,
      "name_simple": "Al-Fatihah",
      "name_complex": "Al-Fatihah",
      "name_arabic": "الفاΨͺΨ­Ψ©",
      "verses_count": 7,
      "pages": [1, 1],
      "translated_name": {
        "language_name": "english",
        "name": "The Opener"
      }
    },
    {
      "id": 2,
      "revelation_place": "madinah",
      "revelation_order": 87,
      "bismillah_pre": true,
      "name_simple": "Al-Baqarah",
      "name_complex": "Al-Baqarah",
      "name_arabic": "Ψ§Ω„Ψ¨Ω‚Ψ±Ψ©",
      "verses_count": 286,
      "pages": [2, 49],
      "translated_name": {
        "language_name": "english",
        "name": "The Cow"
      }
    }
    // ... more chapters
  ]
}

⚠️ Important Considerations​

Environment Configuration​

danger

🚩 Do not mix tokens between environments! Access tokens are environment-specific and cannot be used across different environments.

EnvironmentAuth URLAPI Base URLUsage
Pre-Productionhttps://prelive-oauth2.quran.foundationhttps://apis-prelive.quran.foundationFor testing and development
Productionhttps://oauth2.quran.foundationhttps://apis.quran.foundationFor live applications

Disable Browser Auto-translate​

Set <meta name="google" content="notranslate">, translate="no" on containers, or a CSP header (`X-Content-Security-Policy: translate 'none') so users never see machine-re-translated Quranic text.

πŸ”„ Migrating from api.quran.com​

If you previously used the unauthenticated API at:

https://api.quran.com/api/v4/...

please note that the new APIs require OAuth2 authentication and use a different base URL.

Steps to migrate:

  1. Request API access β€” see instructions above.

  2. Obtain your client credentials and token β€” follow the Authentication section.

  3. Update your base URL:

    • Pre-Production:

      https://prelive-oauth2.quran.foundation/content/api/v4/...

    • Production:

      https://oauth2.quran.foundation/content/api/v4/...

  4. Add authorization headers β€” follow Use the Access Token to include your token and client ID with each request.

That’s it β€” the endpoints, query parameters, and responses remain unchanged.

❌ Common Issues & Troubleshooting​

Error CodeMeaningSolution
400Bad RequestCheck your request parameters and format.
401UnauthorizedVerify your access token is valid and not expired.
403Forbidden / Wrong ScopeEnsure your token has the correct permissions.
429Rate Limit ExceededReduce request frequency or contact support for increased limits.
500Internal Server ErrorContact support if this issue persists.

πŸ’Ό Need Help?​

For any issues or questions, please contact: πŸ“§ developers@quran.com

🟒 Next Steps:

Now that you're authenticated and have successfully made your first API call, explore the API Reference to learn about all available endpoints!