OAuth 2.0

The ManageEngine SerivceDesk Plus MSP Cloud APIs use OAuth 2.0 for authentication. This page gives you an overview of the authentication process. For complete details on OAuth 2.0 flows, registration, token management, and more, refer to Zoho OAuth 2.0 documentation.

How OAuth 2.0 works

To access SerivceDesk Plus MSP Cloud APIs, your application needs an access token obtained through one of the

OAuth 2.0 flows. At a high level, the steps are:

• Register your application in the Zoho API console.

• Get consent from user to access their data and obtain an access token.

• Call SerivceDesk Plus Cloud APIs using the access token.


Token Expiry

Access tokens expire periodically. The expiry duration is mentioned as expires_in (seconds) in the access token response. To maintain uninterrupted access, you can request for an optional refresh token, store it, and use it to generate new access tokens as needed.

Different OAuth flows for different app types

Zoho supports OAuth flows for different application types (server-based, client-based, mobile & desktop-based, limited input devices, and self client). You can choose the flow that matches your application.

Multi DC support

Zoho operates data centres in multiple regions. If your application serves users across regions, you must enable Multi DC support in the API console and use region-specific endpoints for both OAuth and Product API calls.

See detailed OAuth 2.0 workflow

Scopes

ManageEngine ServiceDesk Plus MSP 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.

Customer Scopes

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.

For more details about scope format, see OAuth Scopes.​ ​

Making API calls with access token

To authenticate your API calls, include the access token in the Authorization header of every API request.

Supported Format

Authorization: Zoho-oauthtoken <space> {access-token-value}

API endpoints by data center

When making API calls, you must use the base URL corresponding to your user’s data center. The correct URL is returned as api_domain in the access token response.

For more details about Data Centres, see Multi-DC Support.​

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 <service domain|custom domain>/app/<portal>/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 = "<service domain|custom domain>/app/<portal>/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 = "<service domain|custom domain>/app/<portal>/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 = "<service domain|custom domain>/app/<portal>/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"
            },
            "customer": {
                "name": "Cutomer 1",
                "id": "2000000041633",
                "is_msp": false,
                "deleted_time": null
            }
        }]
    }