OAuth 2.0

The ManageEngine ServiceDesk Plus Cloud API uses the OAuth2.0 protocol for authentication. It uses the Authorization Code Grant Type to obtain the Authorization Code / Grant Token (Code).

This Grant Type allows you to share specific data with any application while keeping your usernames and passwords private. This protocol provides users with a secure and easy way to use authentication.

• Why use OAuth 2.0?


• How OAuth 2.0 works?


• Terminologies


• Tokens


• Scopes

• API Example
• Encoding Input Data

Why use OAuth 2.0?

• You can revoke a customer’s access to their application any time.

• No need for disclosing credentials to clients.

• No information will be revealed even if the client is hacked, since access tokens are issued to individual applications and not the client as a whole.

• Specific scopes can be applied to either restrict or provide access to certain data for the client. It would be different for each client’s application.

How OAuth 2.0 works?

Terminologies

Following are some terms you need to know before you start using the ManageEngine ServiceDesk Plus Cloud APIs.

Protected resources

The ManageEngine ServiceDesk Plus Cloud resources, such as Requests, Changes, Projects, Tasks, etc.

Resource Server

The ManageEngine ServiceDesk Plus Cloud server that hosts the protected resources.


Resource Owner

Any end user of your account, who can grant access to the protected resources.


Client

An application that sends requests to the resource server to access the protected resources on behalf of the end user.


Client Id

The consumer key generated from the connected application.

Client Secret

The consumer secret generated from the connected application.


Authentication server

The Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client. In this case, it will be the ManageEngine ServiceDesk Plus Cloud authorization server.


Grant Token / Authorization Code

A temporary token created by the authorization server and sent to the client via the browser. The client will send this code to the authorization server in order to obtain an access and refresh tokens.


Access Token

A token that is sent to the resource server to access the protected resources of the user. The Access token provides a secure and temporary access to ManageEngine ServiceDesk Plus Cloud APIs and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour, and can be used only for the set of operations that is described in the scope.


Refresh Token

A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the user.


Token Validity

Each access token is valid for only an hour and used only for the operations defined in the scope.
Refresh token does not expire. Use it to refresh access tokens when they expire
You can only generate a maximum of five refresh tokens in a minute.
To know more about Validity of the Token Limit, Pls visit this link.

Scopes

ManageEngine ServiceDesk Plus Cloud APIs use selected scopes, which control the type of resource that the client application can access. Tokens are usually created with various scopes to ensure improved security.

For example, you can generate a scope to create or view a service request, or to view metadata and so on. Scopes contain three parameters — service name, scope name, and operation type. The format to define a scope is

scope=SDPOnDemand.scope_name.operation_type

Example: scope=SDPOnDemand.projects.ALL

Here, SDPOnDemand is the service name, projects is the scope name, and ALL is the operation type.


List of Available Scopes

Group/Module scope provides complete access to all functions the user can perform on the particular module.

For instance, a group scope can allow a user to read, create, update, and delete records in a module.

Requests Scopes

Problems Scopes

Changes Scopes

Projects Scopes

Releases Scopes

Assets Scopes

CMDB Scopes

Contracts Scopes

Purchases Scopes

Custom Module Scopes

Solutions Scopes

Setup Scopes

General Scopes

One or more scopes can also be mentioned as comma separated in scope.

Example:

scope=SDPOnDemand.requests.ALL,SDPOnDemand.projects.READ,SDPOnDemand.setup.READ,SDPOnDemand.setup.CREATE

Here, Request, Project and Admin modules are included in scope. So this will provide complete access for request module and read access for project module and read and create access for Admin module.

Register Your Application

Before you get started with authorization and make any calls to the ManageEngine ServiceDesk Plus Cloud API you need to register your application with ManageEngine ServiceDesk Plus Cloud API.

To register,

1. Go to Zoho Developer Console.
   

2. Click Add Client.
   

3. Choose a client type.
   

Client Based Applications
Applications that run exclusively on a browser and are independent of a web server.

Server Based Applications
Applications that are clients running on a dedicated HTTP server.

Mobile Based Applications
Applications that are installed on smart phones and tablets.

Non-browser Applications
Applications for devices without browser provisioning such as smart TVs and printers.

Self Client
Stand-alone applications that perform only back-end jobs (without any manual intervention) like data sync.

4.Enter the following details:

Client Name
The name of your application you want to register with ManageEngine ServiceDesk Plus Cloud.

Client Domain
The name of your domain to be used in URLs to identify your application’s web page.

Authorized Redirect URIs
A valid URL of your application to which ManageEngine ServiceDesk Plus Cloud (Zoho Accounts) redirects you with a grant token(Authorization code) after successful authentication.

5.Click Create to receive the following credentials:

Client ID
The consumer key generated from the connected app.

Client Secret
The consumer secret generated from the connected app.

Authorization Request

To authorize your application, you need to redirect the user of the client application to the suitable authorization endpoint. On successful login, ManageEngine ServiceDesk Plus Cloud will call your redirect URI along with an authorization code.

Self-Client

Use this method to generate the grant token if your application does not have a domain and a redirect URL.
You can also use this option when your application is a standalone server-side application performing a back-end job.

1. Go to Zoho Developer Console.
   
2. Click Add Client.
   
3. Choose Self Client from the list of client types.
   
4. Click OK in the pop up to enable a self client for your account.
   
5. Now, your client ID and client secret are displayed under the Client Secret tab.
   

1. Click the Generate Code tab and enter the required scope separated by commas. Refer to our list of Scopes, for more details. The system throws an ‘Enter a valid scope’ error when you enter one or more incorrect scopes.
   
2. Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.
   
3. Enter a description and click Generate.
   

1. The generated code for the specified scope is displayed. Copy the grant token.
   

Server-Based Applications

This method allows the application users to authorize the application and obtain the grant token (code) on the address bar of the browser.After you receive your Client ID, enter the following authorization URL in your browser:

https://accounts.zoho.com/oauth/v2/auth?response_type=code&client_id=1000.15S25B602CISR5WO9RUZ8UT39O3RIH&scope=SDPOnDemand.projects.ALL&redirect_uri=https://www.zoho.com&access_type=offline

Request Parameters

response_type
Value must be ‘code’.

client_id
Obtained from registering your client at the Zoho Accounts developer console.

scope
A scope determines which protected resource of an end-user a client has requested access to. Refer here for scopes.

redirect_uri
The URI endpoint that Zoho Accounts will redirect the web browser to with the authorization code after authorizing the client. (Not required for Self client)

access_type
Enter access_type as online or offline. If you want to generate the refresh token, set this value as offline. If access token is forgotton, enter the following parameter along with access_type to receive a new refresh token.

prompt
Value must be ‘consent’. If this parameter is included in the query, every time you generate an OAuth token, the user’s consent approval will be mandatory.

In the resultant page, click Accept. The browser redirects to the redirect_uri specified during client registration.

Your browser displays the following URL on the address bar:

{redirect_uri}?code={grant_token}&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

Note down the “code={grant_token}” parameter. This is your Grant Token / Authorization Code. Use this token to Generate Access and Refresh Tokens.

Generate Access Token and Refresh Token

OAuth 2.0 requests are usually authenticated with an access token, which is passed as bearer token. To use this access token, you need to construct a normal HTTP request and include it in an Authorization header along with the value of Bearer.

To generate access and refresh token

https://accounts.zoho.com/oauth/v2/token

curl https://accounts.zoho.com/oauth/v2/token 
-X POST  
-H "Content-Type: application/x-www-form-urlencoded" 
-d "code=1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab"
-d "grant_type=authorization_code" 
-d "client_id=1000.QMxxxxMEG7SJMPYU6xxxKDR79IGBC" 
-d "client_secret=27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860"
-d "redirect_uri=https://www.zoho.com"

// Deluge Sample script
url = "https://accounts.zoho.com/oauth/v2/token";
payload = Map();
payload.put("Content-Type","application/x-www-form-urlencoded");
payload.put("code","1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab");
payload.put("grant_type","authorization_code");
payload.put("client_id","1000.QMxxxxMEG7SJMPYU6xxxKDR79IGBC");
payload.put("client_secret","27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860");
payload.put("redirect_uri","https://www.zoho.com");
response = invokeurl
[
    url :url
    type :POST
    parameters:payload
];
info response;

#Powershell version - 5.1
$url = "https://accounts.zoho.com/oauth/v2/token"
$data = @{"code" = "1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab"; 
"grant_type" = "authorization_code";
"client_id" = "1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab"; 
"client_secret" = "27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860"; 
"redirect_uri" = "https://www.zoho.com" }
$response = Invoke-RestMethod -Uri $url -Method post -Body $data  -ContentType "application/x-www-form-urlencoded"
$response

#Python version - 3.8
#This script requires requests module installed in python.
import requests

url = "https://accounts.zoho.com/oauth/v2/token"
data ={"Content-Type": "application/x-www-form-urlencoded",
"code" : "1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab",
"grant_type" : "authorization_code",
"client_id" : "1000.QMxxxxMEG7SJMPYU6xxxKDR79IGBC",
"client_secret" : "27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860",
"redirect_uri" : "https://www.zoho.com" }
response = requests.post(url,data=data,verify=False)
print(response.text)

 {
     "access_token": "1000.2370ff1fd75e968ae780cd8d14841e82.03518d2d1dab9c6c4cf74ae82b89defa",
     "refresh_token": "1000.2afabf2f5a396325e88f715c6de34d12.edce6130ca3832a14e5f80d005a5324d",
     "token_type": "Bearer",
      "expires_in": 3600
  }

Refresh Access Token

https://accounts.zoho.com/oauth/v2/token

curl https://accounts.zoho.com/oauth/v2/token
-X POST  
-H "Content-Type: application/x-www-form-urlencoded" 
-d "refresh_token=1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab" 
-d "grant_type=refresh_token"
-d "client_id=1000.QMxxxxMEG7SJMPYU6xxxKDR79IGBC" 
-d "client_secret=27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860"
-d "redirect_uri=https://www.zoho.com"

// Deluge Sample script
url = "https://accounts.zoho.com/oauth/v2/token";
payload = Map();
payload.put("Content-Type","application/x-www-form-urlencoded");
payload.put("refresh_token","1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab");
payload.put("grant_type","refresh_token");
payload.put("client_id","1000.QMxxxxMEG7SJMPYU6xxxKDR79IGBC");
payload.put("client_secret","27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860");
payload.put("redirect_uri","https://www.zoho.com");           
response = invokeurl
[
    url: url
    type: POST
    parameters: payload
];
info response;

#Powershell version - 5.1
$url = "https://accounts.zoho.com/oauth/v2/token"
$data = @{"refresh_token" = "1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab";
"grant_type" = "refresh_token";
"client_id" = "1000.QMxxxxMEG7SJMPYU6xxxKDR79IGBC";
"client_secret" = "27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860";
"redirect_uri" = "https://www.zoho.com" }@
$response = Invoke-RestMethod -Uri $url -Method post -Body $data -ContentType "application/x-www-form-urlencoded"
$response

#Python version - 3.8
#This script requires requests module installed in python.
import requests

url = "https://accounts.zoho.com/oauth/v2/token"
data ={"Content-Type": "application/x-www-form-urlencoded",
"refresh_token" : "1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab",
"grant_type" : "refresh_token",
"client_id" : "1000.QMxxxxMEG7SJMPYU6xxxKDR79IGBC",
"client_secret" : "27db6a8xxxxx60c2f5655dcc16xx9d19cb5a8860",
"redirect_uri" : "https://www.zoho.com" }          
response = requests.post(url,data=data,verify=False)
print(response.text)

 {
      "access_token": "1000.79f24a5c6b66b2b52b40efc91cd8fae5.4e6143741fd798428e0bd4de25295887",
      "token_type": "Bearer",
      "expires_in": 360
  }

Revoking Refresh Token

https://accounts.zoho.com/oauth/v2/token/revoke

curl https://accounts.zoho.com/oauth/v2/token/revoke
-X POST  
-H "Content-Type: application/x-www-form-urlencoded" 
-d "token=1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab"

// Deluge Sample script
url = "https://accounts.zoho.com/oauth/v2/token/revoke";
payload = Map();
payload.put("Content-Type","application/x-www-form-urlencoded");
payload.put("token","1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab");
response = invokeurl
[
    url: url
    type: POST
    parameters: payload
];
info response;

#Powershell version - 5.1
$url = "https://accounts.zoho.com/oauth/v2/token/revoke"
$data = @{"token" = "1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab"}@       
$response = Invoke-RestMethod -Uri $url -Method post -Body $data -ContentType "application/x-www-form-urlencoded"
$response

#Python version - 3.8
#This script requires requests module installed in python.
import requests

url = "https://accounts.zoho.com/oauth/v2/token/revoke"
data ={"Content-Type": "application/x-www-form-urlencoded",
"token" : "1000.cdeffbc4xxxx2dd1aaae83531662a22.0f8bbxxxx753ac2776d4f1dffed2xab"}
response = requests.post(url,data=data,verify=False)
print(response.text)

   { 
        "status":"success"
   }

API Example

To access the ManageEngine ServiceDesk Plus Cloud’s API, you need to send the ‘Authorization’ & ‘Accept’ headers with your request.

GET LIST Request

 https://sdpondemand.manageengine.com/api/v3/requests

$ curl -G api/v3/requests
      -X GET 
      -H "Accept: application/vnd.manageengine.sdp.v3+json" 
      -H "Authorization: Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx" 
      -H "Content-Type: application/x-www-form-urlencoded"
      --data-urlencode input_data = 
 '{
  "list_info": {
    "search_criteria": {
      "field": "created_time.value",
      "condition": "greater than",
      "value": "1488451440000"
    }
  }
 }'

// Deluge Sample script
url = "api/v3/requests";
headers = {"Accept":"application/vnd.manageengine.sdp.v3+json",
           "Content-Type": "application/x-www-form-urlencoded",
           "Authorization": "Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx"};
input_data = {
  "list_info": {
    "search_criteria": {
      "field": "created_time.value",
      "condition": "greater than",
      "value": "1488451440000"
    }
  }
 };
params = {"input_data": input_data};
response = invokeurl
[
    url: url
    type: GET
    parameters: params
    headers: headers
];
info response;

#Powershell version - 5.1
$url = "api/v3/requests"
$headers = @{"Accept"="application/vnd.manageengine.sdp.v3+json";
 "Authorization"="Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx"}
$input_data = @'{
  "list_info": {
    "search_criteria": {
      "field": "created_time.value",
      "condition": "greater than",
      "value": "1488451440000"
    }
  }
 }'@
$data = @{ 'input_data' = $input_data}          
$response = Invoke-RestMethod -Uri $url -Method get -Body $data -Headers $headers -ContentType "application/x-www-form-urlencoded"
$response

#Python version - 3.8
#This script requires requests module installed in python.
import requests
import json
url = "api/v3/requests"
headers ={"Content-Type": "application/x-www-form-urlencoded",
"Accept":"application/vnd.manageengine.v3+json",
"Authorization" : "Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx"}
list_info ={"list_info": {"search_criteria": {"field": "created_time.value","condition": "greater than","value": "1488451440000"}}}
params = {"input_data" :json.dumps(list_info)}
response = requests.get(url,headers=headers,params=params,verify=False)
print(response.text)

    {
        "response_status": [{
            "status_code": 2000,
            "status": "success"
        }],
        "list_info": {
            "search_criteria": {
                "field": "created_time.value",
                "condition": "greater than",
                "value": "1488451440000"
            }
        },
        "requests": [{
            "subject": "Need an External Monitor",
            "id": "1928813039376938",
            "group": {
                "site": "Custom Site",
                "deleted": false,
                "name": "Hardware Problems",
                "id": "2173326968342823"
            },
            "requester": {
                "email_id": "lincoln@zmail.com",
                "is_technician": false,
                "sms_mail": "linc123@xys_sms.co",
                "phone": "test-phone",
                "name": "Lincoln",
                "mobile": "test-mobile",
                "id": "1650986973829395",
                "photo_url": "https://contacts.zoho.com/file?sample",
                "is_vip_user": false
            },
            "created_time": {
                "display_value": "Nov 10, 2016 11:44 AM",
                "value": "1478758440000"
            },
            "on_behalf_of": {
                "email_id": "lincoln@zmail.com",
                "is_technician": false,
                "sms_mail": "linc123@xys_sms.co",
                "phone": "test-phone",
                "name": "Lincoln",
                "mobile": "test-mobile",
                "id": "2437969736081554",
                "photo_url": "https://contacts.zoho.com/file?sample",
                "is_vip_user": false
            },
            "update_reason": "The request is updated for this reason",
            "has_notes": false,
            "status": {
                "in_progress": false,
                "internal_name": "test-internal_name",
                "stop_timer": false,
                "color": "#ffffff",
                "name": "Open",
                "id": "1846100140604337"
            },
            "template": {
                "is_service_template": false,
                "name": "Default Template",
                "id": "1908186594112074"
            },
            "display_id": "39",
            "is_service_request": false,
            "technician": {
                "email_id": "test@test.com",
                "cost_per_hour": 1343434.4333,
                "phone": "test-phone",
                "name": "Charles",
                "mobile": "test-mobile",
                "id": "1537931074919595",
                "photo_url": "https://contacts.zoho.com/file?sample",
                "sms_mail_id": "test-sms_mail_id"
            },
            "due_by_time": {
                "display_value": "Nov 10, 2016 11:44 AM",
                "value": "1478758440000"
            }
        }]
    }

Encoding input params in Postman

Adding list_info to input_data params in Postman

Params

1. Add Input Params to a Request in Params Tab.
2. Encode the Params by right-clicking the value provided to input_data.
3. Send Request with Encoded input_data in Params