Sample Code

Create Organization related sample code :

var Prism = require('prismjs');
var loadLanguages = require('prismjs/components/');
loadLanguages(['haml']);

// The code snippet you want to highlight, as a string
var code = "= ['hi', 'there', 'reader!'].join \" \"";

// Returns a highlighted HTML string
var html = Prism.highlight(code, Prism.languages.haml, 'haml');
REST API
GUIDE REFERENCE
Access Qntrl

Overview

Qntrl allows developers to build web applications and manage organization details using REST APIs. With Qntrl APIs you can perform most of the operations supported by the web client like get, create, delete, and update.

RESTful APIs are independent of programming languages and lets the developers code in any language like Java, Python, .Net, C, C++, PHP, etc. The response data is also program independent and will be in JSON format. Qntrl APIs allow integration of its modules with third-party applications and services. They also come in handy while building extensions for Qntrl.

Mandatory URL for API

https://coreapi.qntrl.com/blueprint/api/

Authentication

Qntrl APIs use OAuth 2.0 protocol for authentication. User credentials are not exposed to clients in this method, allowing the user to share and manage data securely.

Register your application

To get started with Qntrl API, you need to register your application.

1. Navigate to https://accounts.zoho.com/developerconsole

2. Click Add Client ID.

3. Enter the client name, domain, and authorized redirect URLs.

  • Redirect URI is the callback URL of your application. The user gets redirected to this URL upon successful authorization.

4. Click Create to receive the Client ID and Client Secret.

Note:
  • Make a note of the Client ID and Client Secret to generate authorization code in the next step.

Authorization request

To authenticate your application, construct a URL by passing the required parameters.

https://accounts.zoho.com/oauth/v2/auth?scope={scope}&client_id={client_id}&response_type=code&access_type={offline or online}&redirect_uri={redirect_uri}&prompt=consent

Here is a brief description about the parameters used in the URL.

Parameters:

  • scope: Scope of the application for which the token must be generated.
    Sample Scope: Qntrl.org.READ
    Multiple scopes are separated by comma. Take a look at the scopes supported by Qntrl.
  • client_id: The client ID generated while registering the application. This ID uniquely identifies the application making the request.
  • state: An authentication string used by the client between request and callback.
  • response_type:Specify the response_type value as code.
  • redirect_uri: Specify the Authorized redirect URI mentioned while registering the application.
  • access_type: Specify this value as online or offline. Mention online to generate access tokens. Mention offline to generate both access and refresh tokens.

Once you construct the URL, follow the below steps,

1. Hit this URL on a browser.

Click Accept. You will be redirected to the URI mentioned while registering the application.

Note:
  • On successful authorization, you will receive a code parameter as a query string in the redirect URI. This code is valid for 2 minutes and can be used to get access and refresh tokens in the next step.
  • In case you click Reject, you will still be redirected to the mentioned URI, but code parameter will not be displayed.

Generate access and refresh tokens

Once the authorization is successful, the code generated in the previous step can be exchanged to get access and refresh tokens.

Note: This code can be exchanged only once. If the code expires, it has to be regenerated.

To generate the tokens, hit a POST request to https://accounts.zoho.com/oauth/v2/token, by passing the required parameters in the following URL.

https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id&client_secret={client_secret}&grant_type=authorization_code

Parameters:

  • code: Specify the code obtained in the previous step.
  • redirect_uri: Specify the Authorised redirect URI entered while registering the application.
  • client_id:Specify the Client ID received while registering the application.
  • client_secret: Specify the Client Secret received while registering the application.
  • grant_type: Specify the value as authorization_code.
Note: The access token obtained can be used to make requests in API for the next one hour. Make note of the refresh token to generate new access tokens when the current one expires. Learn more about access and refresh tokens.

Regenerate access tokens

When the current access token expires (usually in an hour), the refresh token can be used to generate a new access token, provided the user is still authorized to the application.

To regenerate access token, hit a POST request to https://accounts.zoho.com/oauth/v2/token, by passing the required parameters in the following URL.

https://accounts.zoho.com/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token

Parameters:

  • refresh_token: Specify the refresh token obtained while generating the access token in the previous step.
  • client_id: Specify the Client ID received while registering the application.
  • client_secret:Specify the Client Secret received while registering the application.
  • redirect_uri: Specify the Authorised redirect URI entered while registering the application.
  • grant_type: Specify the value as <refresh_token.

Revoking tokens

If the user no longer needs to access the application, they can revoke the access.

To revoke a refresh_token, hit POST method with the following URL.

https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}

Getting Started

To send tokens to Qntrl API, the header must be in the following format,

  • Header Name: Authorization
  • Value: Zoho-oauthtoken<space>authtoken

HTTP methods

Supported HTTP methods are listed here:

Method Purpose
GET To receive data from the server.
POST To add new data to the server and to perform actions.
PUT To update existing data. This replaces the target resource with the updated data.
DELETE To delete data.

Errors

HTTP status codes are displayed in case of success or failure API calls. Commonly used HTTP status codes are listed here:

HTTP status codes

Status Code Description
200 Success
201 Created
400 Bad Request
403 Forbidden (Unauthorized access)
404 Resource not found
405 Method not allowed
500 Internal server error
Note:
  • Ensure if you have used the right method name in case you encounter a 405 error status.

Key Terminologies

Access token

Access token is used to access the resources of the user. It sends requests and provides secure access to Qntrl APIs.

Note:
  • Each access token is valid for an hour.

Refresh token

Refresh token is used to get new access tokens.

Note:
  • Refresh token has unlimited lifetime, until it is resolved by the end user.

Scope

Scope of the application for which the token must be generated.

Take a look at the sample Job scopes supported by Qntrl:

  • scope=Qntrl.job.READ
  • scope=Qntrl.job.CREATE
  • scope=Qntrl.job.UPDATE
  • scope=Qntrl.job.DELETE
  • scope=Qntrl.job.ALL
Note:
  • A few modules may not support all the above scopes.