Skip to main content

Using OAuth 2.0 to Access Quran.Foundation APIs

Quran.Foundation APIs use the OAuth 2.0 protocol for authentication and authorization. Quran.Foundation supports common OAuth 2.0 scenarios such as those for web server, client-side, installed, and limited-input device applications.

To begin, obtain OAuth 2.0 client credentials from Quran.Foundation. Then your client application requests an access token from Quran.Foundation Authorization server, extracts a token from the response, and sends the token to the Quran.Foundation API that you want to access.

This page gives an overview of the OAuth 2.0 authorization scenarios that Quran.Foundation supports, and provides links to more detailed content. For details about using OAuth 2.0 for authentication, see OpenID Connect.

Overview

Here's how the OAuth2 process works in a common scenario where user consent is needed to access their data:

oauth2 process

Obtaining OAuth 2.0 client credentials​

Please contact us to get your client credentials.

Basic steps

All applications follow a basic pattern when accessing a Quran.Foundation API using OAuth 2.0. At a high level, you follow five steps:

  1. Obtain OAuth 2.0 credentials by contacting us.

Contact us to obtain OAuth 2.0 credentials such as a client ID and client secret that are known to both Quran.Foundation and your application. The set of values varies based on what type of application you are building. For example, a JavaScript application does not require a secret, but a web server application does.

  1. Obtain an access token from the Quran.Foundation Authorization server.

Before your application can access private data using a quran.com API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

Some requests require an authentication step where the user logs in with their Quran.Foundation account. After logging in, the user is asked whether they are willing to grant one or more permissions that your application is requesting. This process is called user consent.

If the user grants at least one permission, the Quran.Foundation Authorization server sends your application an access token (or an authorization code that your application can use to obtain an access token) and a list of scopes of access granted by that token. If the user does not grant the permission, the server returns an error.

It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. For example, an app that wants to support saving a bookmark should not request Bookmark access until the user presses the "Bookmark Ayah" button.

To request an access token, you will need to generate an authorization URL. This URL will contain the necessary parameters that will be used to authenticate the request and should include the following parameters:

- response_type: The type of response you are expecting (e.g. “code” for an authorization code)
- client_id: Your application’s Client ID
- redirect_uri: The URL where the user should be redirected after authentication
- scope: The scope of access the user is granting (e.g. “read” to read data from their account)
- state: An optional parameter that can be used to verify the request
  1. Examine scopes of access granted by the user.

Compare the scopes included in the access token response to the scopes required to access features and functionality of your application dependent upon access to a related Quran.Foundation API. Disable any features of your app unable to function without access to the related API.

  1. Send the access token to an API.

After an application obtains an access token, it sends the token to a Quran.Foundation API in HTTP x-auth-token request header.

Access tokens are valid only for the set of operations and resources described in the scope of the token request. For example, if an access token is issued for the Quran.Foundation Bookmark API, it does not grant access to the Quran.Foundation Collection API. You can, however, send that access token to the Quran.Foundation Bookmark API multiple times for similar operations.

  1. Refresh the access token, if necessary.

Access tokens have limited lifetimes. If your application needs access to a Quran.Foundation API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

Note: Save refresh tokens in secure long-term storage and continue to use them as long as they remain valid. {/ Limits apply to the number of refresh tokens that are issued per client-user combination, and per user across all clients, and these limits are different. If your application requests enough refresh tokens to go over one of the limits, older refresh tokens stop working. /}

Example​

We have created an Example OAuth2 client that executes step 2 (authorzation request) and receives a callback with tokens required to perform steps 4 and 5 upon successful authorization request. We have used the Example client to connect to Quran.Foundation Authorization server which can be found here. The generated accessToken resulting from the callback can be used to access V1 resource server APIs listed here.