Skip to content

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?

  • 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?

oauth2.0 works

Important

Access https://www.zoho.com/accounts/protocol/oauth.html for getting an overview on OAuth and Application Registration.


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.


Important

User Access Token & Refresh Token must be kept confidential, since it defines the authentication and type of API that you use. Do NOT expose your Access Token & Refresh Token anywhere in public forums, public repositories or on your website’s client side code like HTML or JavaScript. Exposing it to public may lead to data theft, loss or corruption.


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

Operation Type Scope Example Description
ALL SDPOnDemand.requests.ALL To access Requests module related all APIs
CREATE SDPOnDemand.requests.CREATE To create Requests module related records
READ SDPOnDemand.requests.READ To read Requests module related records
UPDATE SDPOnDemand.requests.UPDATE To update Requests module related records
DELETE SDPOnDemand.requests.DELETE To delete Requests module related records

Problems Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.problems.ALL To access Problems module related all APIs
CREATE SDPOnDemand.problems.CREATE To create Problems module related records
READ SDPOnDemand.problems.READ To read Problems module related records
UPDATE SDPOnDemand.problems.UPDATE To update Problems module related records
DELETE SDPOnDemand.problems.DELETE To delete Problems module related records

Changes Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.changes.ALL To access Changes module related all APIs
CREATE SDPOnDemand.changes.CREATE To create Changes module related records
READ SDPOnDemand.changes.READ To read Changes module related records
UPDATE SDPOnDemand.changes.UPDATE To update Changes module related records
DELETE SDPOnDemand.changes.DELETE To delete Changes module related records

Projects Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.projects.ALL To access Projects module related all APIs
CREATE SDPOnDemand.projects.CREATE To create Projects module related records
READ SDPOnDemand.projects.READ To read Projects module related records
UPDATE SDPOnDemand.projects.UPDATE To update Projects module related records
DELETE SDPOnDemand.projects.DELETE To delete Projects module related records

Assets Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.assets.ALL To access Asset module related all APIs
CREATE SDPOnDemand.assets.CREATE To create Asset module related records
READ SDPOnDemand.assets.READ To read Asset module related records
UPDATE SDPOnDemand.assets.UPDATE To update Asset module related records
DELETE SDPOnDemand.assets.DELETE To delete Asset module related records

CMDB Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.cmdb.ALL To access CMDB module related all APIs
CREATE SDPOnDemand.cmdb.CREATE To create CMDB module related records
READ SDPOnDemand.cmdb.READ To read CMDB module related records
UPDATE SDPOnDemand.cmdb.UPDATE To update CMDB module related records
DELETE SDPOnDemand.cmdb.DELETE To delete CMDB module related records

Contracts Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.contracts.ALL To access Contracts module related all APIs
CREATE SDPOnDemand.contracts.CREATE To create Contracts module related records
READ SDPOnDemand.contracts.READ To read Contracts module related records
UPDATE SDPOnDemand.contracts.UPDATE To update Contracts module related records
DELETE SDPOnDemand.contracts.DELETE To delete Contracts module related records

Purchases Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.purchases.ALL To access Purchases module related all APIs
CREATE SDPOnDemand.purchases.CREATE To create Purchases module related records
READ SDPOnDemand.purchases.READ To read Purchases module related records
UPDATE SDPOnDemand.purchases.UPDATE To update Purchases module related records
DELETE SDPOnDemand.purchases.DELETE To delete Purchases module related records

Custom Module Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.custommodule.ALL To access Custom module instance all APIs
CREATE SDPOnDemand.custommodule.CREATE To create Custom module instance records
READ SDPOnDemand.custommodule.READ To read Custom module instance records
UPDATE SDPOnDemand.custommodule.UPDATE To update Custom module instance records
DELETE SDPOnDemand.custommodule.DELETE To delete Custom module instance records

Solutions Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.solutions.ALL To access Solutions module related all APIs
CREATE SDPOnDemand.solutions.CREATE To create Solutions module related records
READ SDPOnDemand.solutions.READ To read Solutions module related records
UPDATE SDPOnDemand.solutions.UPDATE To update Solutions module related records
DELETE SDPOnDemand.solutions.DELETE To delete Solutions module related records

Setup Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.setup.ALL To access Admin module related all APIs
CREATE SDPOnDemand.setup.CREATE To create Admin module related records
READ SDPOnDemand.setup.READ To read Admin module related records
UPDATE SDPOnDemand.setup.UPDATE To update Admin module related records
DELETE SDPOnDemand.setup.DELETE To delete Admin module related records

General Scopes

Operation Type Scope Example Description
ALL SDPOnDemand.general.ALL To access all General APIs
CREATE SDPOnDemand.general.CREATE To create General records
READ SDPOnDemand.general.READ To read General records
UPDATE SDPOnDemand.general.UPDATE To update General records
DELETE SDPOnDemand.general.DELETE To delete General records

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.

Important

You must use your domain-specific Zoho Developer Console to register your application.
Access https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/data-centers.html for every Data Center’s (DC) Developer Console.

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.

Add Client-1

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.

Add Client-2

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.

Add Client-3

Important

If you don’t have a domain name and a redirect URL, you can use dummy values in their place and register your client.


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.

Important

You must authorization request from your domain specific ZOHO accounts URL as mentioned above. However if you make the authorization request from https://www.accounts.zoho.com, after the request is successful, the system automatically redirects to your domain except CN domain.

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.

self-client

  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.

self-client

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

Important

The grant token is valid only for a minute.The authorization URL has the scope for Users. You can change the scope as per your requirement.

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

Important

For security reasons, pass the below parameters in the body of your request.

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

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

Important

When you click Reject, the browser redirects to the domain with the parameter error=access_denied on the address bar. Your application is denied access to the data in your ManageEngine ServiceDesk Plus Cloud account.

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.

Important

You must use your domain-specific Zoho Accounts URL to generate access and refresh tokens.
Access https://www.zoho.com/accounts/protocol/oauth/multi-dc.html for available data centers (DC).

To generate access and refresh token

Make a POST request with the following URL. Use your domain-specific Zoho accounts URL when you make the request.

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

Important

For security reasons, pass the below parameters in the body of your request.

Request Parameters

code
The authorization code you received as a response to the authorization request.

grant_type
Value must be ‘authorization_code’.

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

client_secret
Obtained from registering your application at the Zoho Accounts developer console.

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) 

Response Parameters

access_token
Access token to access ManageEngine ServiceDesk Plus Cloud APIs

refresh_token
Refresh token to obtain new access tokens

token_type
Type of token obtained. “Bearer” indicates this is an access token.

expires_in
Time in seconds after which the access token expires

Important

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.

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"
 {
     "access_token": "1000.2370ff1fd75e968ae780cd8d14841e82.03518d2d1dab9c6c4cf74ae82b89defa",
     "refresh_token": "1000.2afabf2f5a396325e88f715c6de34d12.edce6130ca3832a14e5f80d005a5324d",
     "token_type": "Bearer",
      "expires_in": 3600
  }


Refresh Access Token

Access tokens expire after an hour of generation. To generate a new access token, use the refresh token you generated earlier. 

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

Request Parameters

refresh_token
Used to obtain a new access token after the old one expires.

grant_type
Value must be ‘authorization_code’.

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

client_secret
Obtained from registering your application at the Zoho Accounts developer console.

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) 

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

Important

Used to obtain a new access token after the old one expires. A refresh token does not expire. The maximum number of allowed refresh tokens per account is 20. The 21st refresh token will replace the first created refresh token.

curl https://accounts.zoho.com/oauth/v2/token 
-X POST  
-H "Content-Type: application/x-www-form-urlencoded" 
-d refresh_token="1000.5463cd202e4xxxxxbc2f500231727a.fd440xxxxxxxx01192ef6357d03b22e" 
-d grant_type="refresh_token" 
-d client_id="1000.QMFGxxxx7SJMPYU62YFKDR79IGBC" 
-d client_secret="27db6a824xxxxx60c2f5655dccxxxx9d19cb5a8860"
-d redirect_uri="https://www.zoho.com"
 {
      "access_token": "1000.79f24a5c6b66b2b52b40efc91cd8fae5.4e6143741fd798428e0bd4de25295887",
      "token_type": "Bearer",
      "expires_in": 360
  }


Revoking Refresh Token

If you want to revoke your refresh token,

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

Request Parameters

token
Refresh token to be revoked.

curl https://accounts.zoho.com/oauth/v2/token/revoke 
-X POST  
-H "Content-Type: application/x-www-form-urlencoded" 
-d token="1000.eccde6053dfxxxxxxx1f1ce0b237f7.555c547725xxxxxxx6362bbe9d25"
   { 
        "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

Important

URI components for input_data needs to be encoded in Request Parameter.

$ curl 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"
 '{
  "list_info": {
    "search_criteria": {
      "field": "created_time.value",
      "condition": "greater than",
      "value": "1488451440000"
    }
  }
 }'
    {
        "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

Key Value
input_data {“list_info”:{“search_criteria”:{ “field”: “created_time.value”, “condition”: “greater than”, “value”: “1488451440000” }}}
  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

Adding Params