Getting Started

ManageEngine Desktop Central now facilitates easy integration with your existing infrastructure using REST APIs. You can perform various desktop management activities easily from a single console. You can find the list of modules for which APIs are available in the side bar, if you need more APIs you can contact us with your requirement.

This document describes prerequisites for using the API.

API - URI Structure

All API URI must be structured in the following format,

<Server URL>/api/{Version}/{Entity}/{Operation|Action}
  • Tags
  • Optional/Mandatory
  • Description
  • Usage
  • Version
  • Mandatory
  • API Version
  • 1.3 ie current API Version
  • Entity
  • Mandatory
  • The module for API
  • e.g. inventory, som, desktop
  • Operation or Action
  • Mandatory
  • Operation or action in the module
  • e.g. computers, computers/installagents

Paginated response

Some API endpoints return responses that consist of array of objects. These are paginated responses that return only subset or page of all the objects for that API.

Page limit and page parameters are used to specify the number of objects per response and which page is to be retrieved.

page={page}&pagelimit={page_limit}

For example, if you want the API to return 10 objects per page and wish to see the second page, add the following line at the end of the API

page=1&pagelimit=10

Search

Search operation can be performed in API endpoints that return paginated responses.

Search type and search column parameters are set to the column name that needs to be searched and the search value is set to the search query.

searchtype={resources}&searchcolumn={computername}&searchvalue={searchvalue}

For example, to search for software containing "Adobe" in inventory software,add the following line at the end of the API

searchtype=software_name&searchcolumn=software_name&searchvalue=Adobe

Authentication

Auth token is required for accessing our API. To obtain auth token follow these steps.

Authentication API Endpoint

/api/1.3/desktop/authentication

1(a). Generate Token through local authentication

Send POST request with HTTP header Content-Type:application/json and following JSON in request body to the authentication API.

POST /api/1.3/desktop/authentication

{ 
 "username":<Username>,
 "password":<Password base64 encoded>, 
 "auth_type":"local_authentication" 
}
      

1(b). Generate Token through AD Authentication

Domain Names can be fetched fetched from server discover api. Send POST request with HTTP header Content-Type:application/json and following JSON in request body to the authentication API.

POST /api/1.3/desktop/authentication

{ 
 "username":<Username>,
 "password":<Password base64 encoded>, 
 "auth_type":"ad_authentication" ,
 "domainName": <Domain name>
}

2. Obtain Auth Token from the response

{ "message_type": "authentication", "message_response": {"authentication": { "user_permissions": { "read": ["Common_Read","SOM_Read", "Tools_Read"], "admin": ["Common_Admin","SOM_Admin","Tools_Admin" ], "write": [ "Common_Write","SOM_Write","Tools_Write"] },"user_data": { "auth_type": "Local Authentication", "user_id": 1, "user_name": "admin", "phone_number": null, "email": "" }, "auth_data": { "auth_token": "B42550F3-006D-48EB-8011-F6C7D6323EE7"} } }, "message_version": "1.0", "status": "success" } 

3. Set Auth Token to request header

Set the authtoken from to Authorization HTTP header for all requests.

For a token B42550F3-006D-48EB-8011-F6C7D6323EE7 set header as

Authorization:B42550F3-006D-48EB-8011-F6C7D6323EE7

Generation of Base64 encoded password

  1. From Desktop Central's web console, navigate to Admin -> API Explorer.
  2. On the left pane, click Authentication -> Login.
  3. Choose the authentication type as either Local authentication or AD authentication and furnish the user name and password.
  4. Upon execution, you will obtain base64 encoded password along with the auth token.

Two factor Authentication

If two factor authentication is enabled, perform the following steps to obtain auth token:

  1. While making a request for Authentication API Endpoint, instead of receiving the above-specified response, the following response will be obtained -
    {
        "message_type": "authentication",
        "message_response": {
            "authentication": {
                "two_factor_data": {
                    "unique_userID": "admin85424",
                    "is_TwoFactor_Enabled": true,
                    "message": "Google authentication already created for this user. Validate OTP",
                    "remember_token_days": 1,
                    "OTP_Validation_Required": true
                }
            }
        },
        "message_version": "1.0",
        "status": "success"
    }
    
  2. You will have to make use of the Unique User ID from this response and make the following request:
    POST api/1.3/desktop/authentication/otpValidate
    
    { 
     "uid":"admin85424", 
     "otp":"761666",
     "rememberme_enabled":"true"
    }   
    
  3. The OTP specified here will be generated either via the Authenticator app you are using or the registered mail address, depending on the mode of authentication enabled for two factor authentication.
  4. Upon execution, the auth token will be generated.
    { "message_type": "authentication", "message_response": {"authentication": { "user_permissions": { "read": ["Common_Read","SOM_Read", "Tools_Read"], "admin": ["Common_Admin","SOM_Admin","Tools_Admin" ], "write": [ "Common_Write","SOM_Write","Tools_Write"] },"user_data": { "auth_type": "Local Authentication", "user_id": 1, "user_name": "admin", "phone_number": null, "email": "" }, "auth_data": { "auth_token": "B42550F3-006D-48EB-8011-F6C7D6323EE7"} } }, "message_version": "1.0", "status": "success" } 
Desktop Central - Cloud

OAuth 2.0 can be used to authorize a third-party application to use Desktop Central Cloud resources related to a particular user in a secure manner.

  • Step 1: A user wants to use a third-party application/ integration to access or automate Desktop Central Cloud.
  • Step 2: The third-party app connects with Desktop Central Cloud and requests a token on behalf of the user using this API.
  • Step 3: Desktop Central Cloud provides a temporary token and a secret code to the third-party app. The secret code is to prevent any forgery and for the server to identify the application from which the requests come in.
  • Step 4: The app redirects the user to Desktop Central Cloud along with the temporary token and the secret code. In Desktop Central Cloud, the user sees a prompt to Authorize the third-party app to access his account and data.
  • Step 5: The user authorizes the third-party app. At this point, the third-party app provides the temporary token along with the secret code and gets a Permanent Access Token using this API.
  • Step 6: All the future actions of the user through the app will be done via the Access Token and the Secret code.
  • Third-Party app - Get Client ID and Client Secret

    You need to register the app with the Zoho Developer console to get the Client ID and Client Secret. To register your application, follow the instructions below:

    • Navigate to the Zoho Developer Console.
    • In the API Credentials page, click on Add Client ID to create a new Client ID and Client Secret.
    • OAuth 2.0

    • Provide the Client Name, Client Domain and the Authorized redirect URIs. (The redirect URI is the callback entry point of the app and is different from the entry point of the app.)
    • OAuth 2.0

    • You will get a set of OAuth 2.0 details with the Client ID and Client Secret shared only between Zoho and the application.
    • OAuth 2.0

      Getting Authorization

      Next, you will have to call the Authorization URI - https://accounts.zoho.com/oauth/v2/auth

      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}

      The Authorization URI should contain the following parameters as a query string:

      • Parameter
      • Type
      • Description
      • *client_id
      • Unique Identifier
      • The ID that was assigned to your app when you registered it.
      • *response_type
      • string
      • "code"
      • *redirect_uri
      • URI
      • Your callback URI which you used during registration.
        Specifies the scope allowed for your app. Has to be separated by commas.
      • *scope
      • string
      • Syntax:
        Servicename.scopename.Operation
        Example: DesktopCentralCloud.restapi.READ, DesktopCentralCloud.restapi.Update
      • access_type
      • string
      • offline/online (Default value: online).
        The "online" access_type gives your application only the access_token which is valid for one hour.
        The "offline" access_type will give the application an access_token as well as a refresh_token.
      • prompt
      • string
      • prompt=consent
        Prompts for user consent each time your app tries to access user credentials
      • state
      • string
      • A generated value that correlates the callback with its associated authorization request

      *Mandatory parameters

      Example

      GET oauth/v2/auth

      Host:: https://accounts.zoho.com

      Query String:

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

      ?response_type=code

      &client_id=1000.R2*************************5EN

      &scope=DesktopCentralCloud.restapi.READ,DesktopCentralCloud.restapi.Update

      &redirect_uri=https://zylkerapps.com/oauth2callback

      &state=-54****************5

      Once this Authorization URI is called, the user is shown a 'User consent page'.

      If the user clicks Accept, Zoho redirects the user back to your site with an 'Authorization code'. Your application can now request Zoho for an Access Token using the auth_code. If the user clicks Deny then the server returns an error.

      Prompting re-consent

      You can prompt the user to re-authorize your app every time the user logs in by adding the prompt=consent parameter to the authentication request. When prompt=consent is included, the consent screen is displayed while the user logs into your app. For this reason, include prompt=consent only when necessary.

      Note: The prompt=consent parameter is mandatory while fetching the Refresh Token.

      Getting the Access Token

      Once your application receives the Authorization code, a new request can be made to receive an Access Token using which your app will receive the user credentials. As this is an important step in the entire process, please be careful while setting the parameters for the same.

      • Parameter
      • Type
      • Description
      • *code
      • string
      • Authorization code obtained from the initial request
      • *client_id
      • Unique Identifier
      • The ID that was assigned to your app when you registered it
      • *client_secret
      • string
      • Your app's secret. Assigned when you register your app, which is available in your profile
      • *redirect_uri
      • URI
      • Your callback URI as given during the time of application registration
      • *scope
      • string
      • Specifies the scope allowed for your app. Has to be separated by commas
      • *state
      • string
      • Has to be maintained the same during the entire process of authorization
      • grant_type
      • string
      • "authorization_code"

      *Mandatory parameters

      Response

      Once the request along with the Authorization code is sent, Zoho will issue a response to your app which will give you the following information.

      • expires_in - Time in milliseconds for which the token remains valid.
      • token_type - Type of token. ("bearer")
      • access_token - Access Token for the user. This token can be used for the final API calls and will be valid only for an hour.
      • refresh_token - Refresh Token to use when the Access Token has timed out. This token is permanent and can be used multiple times to refresh the app and get a new Access Token.

      You can store this data so that there is no need for authorization each time this user accesses your app.

      Example

      POST oauth/v2/token

      HOST:: https://accounts.zoho.com

      Query String:

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

      ?code=1000.****************************f160

      &grant_type=authorization_code

      &client_id=1000.R2Z0W*********************Q5EN

      &client_secret=39c**********************************921b

      &redirect_uri=https://zylkerapps.com/oauth2callback

      &scope=DesktopCentralCloud.restapi.READ,DesktopCentralCloud.restapi.Update

      Using the Access Token

      Send the Access Token as a header when you call a Desktop Central Cloud REST API.

      Example

      GET oauth/user/info

      Query String:

      GET

      HOST: https://accounts.zoho.com/

      Header:

      Authorization= Zoho-oauthtoken

      When this Access Token with the available scopes invokes the URI, the info as permitted in the scope is granted to the application. The user credentials are thus obtained and the regular signup flow can be implemented.

      Access Token Expiry

      In your request for access, you can request a Refresh Token to be returned along with the Access Token. A Refresh Token allows Rest APIs to access your applications even when the user is not logged in. To request a Refresh Token, add access_type=offline to the authentication request.

      The Refresh Token will always be generated by the prompt=consent. The maximum number of Refresh Tokens is 20. Once the limit is reached, the first Refresh Token generated will be deleted.

      The Access Tokens have limited validity. In most cases, the Access Tokens expire in one hour. Until then, the Access Token has unlimited usage. Once it expires, your app will have to use the Refresh Token to request for a new Access Token.

      For this new request, the parameters to be included are:

      • Parameter
      • Type
      • Description
      • client_id
      • Unique Identifier
      • The ID that was assigned to your app when you registered it.
      • client_secret
      • string
      • Your app's secret
        Assigned when you register your app and available in your profile.
      • grant_type
      • string
      • refresh_token
      • redirect_uri
      • URI
      • Your callback URI
      • refresh_token
      • string
      • The Refresh Token provided along with the Access Token

      Example

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

      HOST:: https://accounts.zoho.com

      Query String:

      ?refresh_token=1000.4069dacb56****************************************bcf902062390367

      &grant_type=refresh_token

      &client_id=1000.R2Z0W*********************Q5EN

      &client_secret=39c**********************************921b

      &redirect_uri=https://zylkerapps.com/oauth2callback

      &scope=DesktopCentralCloud.restapi.READ,DesktopCentralCloud.restapi.Update

      You will now receive a new Access Token using which you can continue getting user credentials. This Access Token will also have a time limit of one hour. Some APIs need Admin authentication to be executed, and some APIs will be executed only with user authentication. There are certain APIs that can be executed both by the Admin and the User. But, the request URLs will differ according to the role.

Desktop Central - Self-Client
  • Step 1: Add client ID in the Zoho accounts developer console.
    1. Provide a client name.
    2. Provide localhost for client domain.
    3. Provide http://localhost/callback for Authorized redirect URIs.
    4. Copy the client ID & client secret. This is required for the next step.
    5. Click on the options button of the appropriate client name and choose self-client.
    6. Provide the following as scope name
      DesktopCentralCloud.restapi.READ, DesktopCentralCloud.restapi.UPDATE.
    7. Set the expiry time to 10 mins.
    8. Copy the code.
  • Note: This code is valid only for 10 minutes.

  • Step 2: Getting access token
  • Now make the following POST request using the postman after replacing the client id,client secret and code

    https://accounts.zoho.com/oauth/v2/token?client_id <client_id>&grant_type=authorization_code&client_secret<client_secret>&redirect_uri=http://localhost/callback&code=<code>

    You will receive the access token and refresh token in the below format

    {
    "access_token": "*****************************************************************",
    "refresh_token": "***************************************************************",
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer",
    "expires_in": 3600
    }

  • Using refresh token, you can generate access token every 1 hour. Find the document here in Access Token Expiry https://desktopcentral.manageengine.com/apiExplorer.do?actionToCall=showAPIExpPage&did=726990596&buildno=