I. Introduction

MangoApps is now a standards-compliant OAuth 2.0 Authorization Server supporting the OAuth 2.0 framework (RFC 6749) and Bearer Token Usage (RFC 6750) specifications. MangoApps supports two types of OAuth 2.0 tokens – Authorization Code and Implicit. You can use any OAuth 2.0 or HTTPS client library to connect with MangoApps

II. OAuth Roles

  • Resource Owner: MangoApps User – The resource owner is the user who authorizes an application to access their account. The application’s access to the user’s account is limited to the “scope” of the authorization granted (e.g., read or write access only).
  • Resource or Authorization Server: MangoApps API – The resource server hosts the protected user accounts, and the authorization server verifies the identity of the user then issues access tokens to the application. From an application developer’s point of view, a service’s API fulfills both the resource and authorization server roles. We will refer to both of these roles combined, as the Service or API role.
  • Client: Application – The client is the application that wants to access the user’s account. Before it may do so, it must be authorized by the user, and the authorization must be validated by the API.

Here is a more detailed explanation of the steps in the diagram:

The application requests authorization to access MangoApps resources from the user

  1. If the user authorized the request, the application receives an authorization grant
  2. The application requests an access token from the authorization server (API) by presenting authentication of its own identity and the authorization grant
  3. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the application. Authorization is complete.
  4. The application requests the resource from the MangoApps (API) and presents the access token for authentication
  5. If the access token is valid, the MangoApps (API) serves the resource to the application

This is a generic flow. The actual flow of this process will differ depending on the authorization grant type in use.

III. Application Registration

Before using OAuth with your application, you must register your application with MangoApps.

Below are the steps to perform app registration:

a. Login to MangoApps
b. Navigate to the Admin portal
c. Click on Integration > Oauth 2 App
d. Click on ‘Create a New App’
e. Enter the app details and agree to the Terms & Conditions to create the App

The redirect URL is where MangoApps will redirect the user after they authorize (or deny) your application, and therefore the part of your application that will handle authorization codes or access tokens.
You can view the list of registered apps under ‘Registered Apps’ tab

Client ID and Client Secret

Once your application is registered, MangoApps will issue “client credentials” in the form of a client identifier and a client secret.
The Client ID is a publicly exposed string that is used by the service API to identify the application and is also used to build authorization URLs that are presented to users.

The Client Secret is used to authenticate the identity of the application to the service API when the application requests to access a user’s account and must be kept private between the application and the API.

IV. Authorization Grant

In the Abstract Protocol Flow above, the first four steps cover obtaining an authorization grant an access token.
The authorization grant type depends on the method used by the application to request authorization, and the grant types supported by the API.
OAuth 2.0 defines four grant types, each of which is useful in different cases:

a) Authorization Code: used with server-side Applications
b) Implicit: used with Mobile Apps or Web Applications (applications that run on the user’s device)
c) Resource Owner Password Credentials: used with trusted Applications, such as those owned by the service itself
d) Client Credentials: used with Applications API access

Note: Currently MangoApps supports Authorization Code and Implicit Grant Types

Grant Type: Authorization Code

The authorization code grant type is the most commonly used because it is optimized for server-side applications,
where source code is not publicly exposed, and Client Secret confidentiality can be maintained.
This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the user’s web browser) and receiving API authorization codes that are routed through the user-agent.

Step 1: Authorization Code Link

First, the user is given an authorization code link that looks like the following:


Step 2: User Authorizes Application
When the user clicks the link, they must first log in to the MangoApps, to authenticate their identity (unless they are already logged in).
Then they will be prompted by the MangoApps to authorize or deny the application access to their account.
Here is an example authorize application prompt:

Step 3: Application Receives Authorization Code
If the user clicks “Authorize Application”, the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code.
The redirect would look something like this (assuming the application is “myapplication.com”):


Step 4: Application Requests Access Token
The application requests an access token from the API, bypassing the authorization code along with authentication details, including the client secret, to the API token endpoint.

Here is an example POST request to MangoApps’s token endpoint:


Step 5: Application Receives Access Token
If the authorization is valid, the API will send a response containing the access token (and optionally, a refresh token) to the application.
The entire response will look similar to one below:

Now the application is authorized! It may use the token to access the user’s account via the MangoApps API, limited to the scope of access until the token expires or is revoked.
If a refresh token was issued, it may be used to request new access tokens if the original token has expired.

Grant Type: Implicit

The implicit grant type is used for mobile apps and web applications (i.e., applications that run in a web browser), where the secret client confidentiality is not guaranteed.

The implicit grant type is also a redirection-based flow, but the access token is given to the user-agent to forward to the application so that it may be exposed to the user and other applications on the user’s device. Also, this flow does not authenticate the identity of the application, and relies on the redirect URI (that was registered with the service) to serve this purpose.
The implicit grant type does not support refresh tokens.

The implicit grant flow primarily works as follows:
~ the user is asked to authorize the application,
~ then the authorization server passes the access token back to the user-agent, which passes it to the application.

Step 1: Implicit Authorization Link
With the implicit grant type, the user is presented with an authorization link, that requests a token from the API.
This link looks just like the authorization code link, except it is requesting a token instead of code (note the response type “token”):


Step 2: User Authorizes Application
When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in).
Then they will be prompted by MangoApps to authorize or deny the application access to their account.
Here is an example authorize application prompt:

Step 3: User-agent Receives Access Token with Redirect URI
If the user clicks “Authorize Application,” MangoApps redirects the user-agent to the application redirect URI and includes a URI fragment containing the access token.
It would look something like this:


Step 4: User-agent Follows the Redirect URI
The user-agent follows the redirect URL but retains the access token.

Step 5: Application Sends Access Token Extraction Script
The application returns a webpage that contains a script that can extract the access token from the full redirect URI that the user-agent has retained.

Step 6: Access Token Passed to Application
The user-agent executes the provided script and passes the extracted access token to the application.

Now the application is authorized! It may use the token to access the user’s account via MangoApps API, limited to the scope of access until the token expires or is revoked.

V. User Portal: Revoke Authorized Applications

Authorized applications can read and write your data. However, you may revoke the authorization of individual apps from user portal. Once revoked the app will not be able to read or write your data unless you authorize again.

Below are the steps to revoke an application, under the Authorized app:

a. Login to MangoApps
b. Navigate to the ‘Change My Settings > Authorized App’
c. Select the app and click on ‘Revoke’ users

Note that ‘Revoke’ of Authorized App is a user-specific setting which each of the user can perform to revoke an application.


VI. Demo Working App



  • Click on ‘Login with MangoApps’
  • You will be navigated to the portal MangoApps login portal of siddqa.mangopulse.com
  • Enter the username: admin@siddqa.com and password: temp123
  • This will log you into MangoApps which will then authenticate the 3rd party application (Below is a dummy app)


How To Use MangoApps as an OAuth 2.Provider – Video