Introduction

The ManageEngine Endpoint Central API provides a comprehensive interface to facilitate seamless integration with third-party tools. By leveraging these APIs, you can automate endpoint management tasks within your IT ecosystem that often require collaboration across multiple tools.

The APIs allow you to fetch and modify data across various Endpoint Central modules, including Inventory, Patch Management, Configurations, MDM, and more.

All APIs follow standard HTTP methods and error codes and support commonly used data formats such as JSON.

You can find the list of supported modules that offer APIs in the left sidebar. If you require additional APIs, please contact us with your requirements..

OAuth 2.0 for APIs - An Overview

The Zoho Product's API uses the OAuth 2.0 protocol for authentication. OAuth 2.0 is an industry-standard protocol specification that enables third-party applications (clients) to gain delegated access to protected resources in Zoho via an API.

• Why should we use OAuth 2.0?
• How OAuth 2.0 works?
• Key Terminologies in OAuth 2.0
• Tokens

Why should we use OAuth 2.0?

• Clients are not required to support password authentication or store user credentials.
• Clients gain delegated access, i.e., access only to resources authenticated by the user.
• Users can revoke the client's delegated access anytime.
• OAuth 2.0 access tokens expire after a set time. If the client faces a security breach, user data will be compromised only until the access token is valid.

How OAuth 2.0 works?

Key Terminologies in OAuth 2.0

The following are some terms you need to know before you start using the Zoho Product's APIs.

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

Authorization server provides the necessary credentials (such as Access and Refresh tokens) to the client.

Authentication code

The authorization server creates a temporary token and sends it to the client via the browser. The client will send this code to the authorization server to obtain access and refresh tokens.

Tokens

Access Token

A token that is sent to the resource server to access the protected resources of the user. The Access token provides secure and temporary access to the protected resources 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 are 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 end-user.

Important

User Access Token must be kept confidential since it provides access to protected resources. Do NOT expose your Access Token anywhere in public forums, public repositories or on your website's client-side code like HTML or JavaScript. Exposing it to the public may lead to data theft, loss or corruption.

Scopes

Scopes limit the level of access given to a client for protected resources. It enables a user to provide delegated access to a client. Zoho Service 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 lead, 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=service_name.scope_name.operation_type

For example, ZService.modules.ALL

Here, ZService is the service API name, modules is the scope name, and ALL is the operation type.

• Service API name is the name of the service the client is making API calls to.
• Scope name is the name of the module in the service the client needs access to.
• Operation type is the type of operation that is permissible for the client. It can be ALL, CREATE, READ, UPDATE, DELETE. (ALL gives access to perform all operations).

Group Scopes

Group scope provide complete access to all functions the user can perform on the record. For instance, a group scope can allow a user to read, create, update, and delete records in all modules.

Example:

https://accounts.zoho.com/oauth/v2/auth?scope=ZService.modules.ALL,ZService.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

In the above example, the user has access to all modules in the client ZService account.

Other examples are

• scope=ZService.modules.READ(Read-only permission)
• scope=ZService.modules.CREATE
• scope=ZService.modules.UPDATE
• scope=ZService.modules.DELETE

Separate Scopes

Separate scopes are used to provide access to data in a particular module without access to other modules.

https://accounts.zoho.com/oauth/v2/auth?scope=ZService.modules.leads.ALL,ZService.modules.deals.ALL,ZService.settings.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The above scope gives the user access to only the leads and deals modules from the client Zoho Service account.

Additionally, you can set specific permissions, like read, create, update or delete, for each module. For examples:

• scope=ZService.modules.leads.READ(Read-only permission)
• scope=ZService.modules.leads.CREATE
• scope=ZService.modules.leads.UPDATE
• scope=ZService.modules.leads.DELETE

Multiple Scopes

Access tokens can also be generated with multiple scopes. In such cases, the scopes should be separated by commas. The format to provide multiple scope is service_name.scope_name.OPERATION_TYPE,service_name.scope_name.OPERATION_TYPE. For example, ZService.modules.READ,ZService.settings.READ.

Register your Application

Before you get started with authorization and make any calls using the Zoho Service APIs, you need to register your application with Zoho Service.

To register,

1. Go to Zoho Developer Console and click on GET STARTED.

   

2. Choose a client type and click CREATE NOW:

   

   Types of Clients

   • Client-based Applications

     Applications that run exclusively on a browser and are independent of web servers.

   • Server-based Applications

     Applications that are intended for use by multiple Zoho accounts. This app could be solving a special use case for all Zoho accounts and should have both a dedicated backend server and web UI to handle the authorization process and the app's logic. The app redirects users to Zoho for the authorization process using a web browser. Users grant permission for the app to access their Zoho data on their behalf. The app will consume data for its intended purposes on behalf of the user who authorized the app.

   • Mobile-based Applications

     Applications that are built to run on smart phones and tablets.

   • Non-browser Mobile Applications

     Applications that run on devices without browsers such as smart TVs and printers.

   • Self Client

     Applications that does not have a redirect URL or a web UI, operating solely in the backend without requiring user interaction. A self-client is commonly employed when both the application and Zoho services are managed by the same person, aiming to establish secure communication between them.

   For more details, refer to OAuth Overview.

   Note

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

3. Enter mandatory entries for corresponding client type and click on CREATE.

   Mandatory Entries for Different Client Types

   The following are the mandatory entries for different client types.

   Client Type	Client Name	Homepage URL	Redirect URIs	JS Domains
   Java Script	Y	Y	Y	Y
   Web-based	Y	Y	Y	NA
   Mobile	Y	Y	Y	NA
   Self Client	N	N	N	NA
   Device	Y	Y	N	NA

   • Server-based applications

     

   • Client-based applications

     

   • Self client

     

4. You will receive the client credentials such as Client ID and Client Secret in the Client Secret tab.

Possible Errors

• Enter a valid client name

  Resolution: The client name has a special character. The client name must not contain any special characters except "_" and "&".

• Enter a valid JavaScript Domain URI

  Resolution: The JavaScript domain is incorrect. Specify valid JavaScript domains, separated by commas, and they must start with 'http'.

• Enter a valid redirect URI

  Resolution: The redirect URI is incorrect. Specify a valid redirect URI in the format "https://www.your-domain.com/callback".

• Enter a valid homepage URL

  Resolution: The homepage URL is invalid. Specify a valid homepage URL in the format "https://www.yourdomain.com".

Authorization Request

To use the Zoho Service APIs, the users must authenticate the application to make API calls on their behalf with an access token.

The access token, in return, must be obtained from a grant token (authorization code). The Zoho Service APIs use the authorization code grant type to provide access to protected resources.

Note

Organization-Specific Grant Token (Authorization Code)

• The user can choose to grant access to the application only to a particular organization (either in the Production, Sandbox, or Developer environment of ZService). Therefore, the access and refresh token generated for a user becomes organization-specific in an environment. For instance, the application owner cannot use tokens generated for an organization in the Production environment to make API calls to the organizations in the sandbox or developer accounts.
• If your web-based application has more than one organization in multiple environments (for instance, one in production, and two each in sandbox and developer environments), the user will be allowed to choose the organization for which the grant token must be generated. On the contrary, if your application has only one organization (for instance, one in production and none in sandbox or developer environments), the system automatically generates the grant token for the same, without asking for any choices.
• For self-clients, the system presents the list of available organizations, irrespective of the number of organizations in your application.

There are three ways in which you can generate the grant token based on the client type.

* Web-based application * Self-client - Authorization code flow * Self-client - Client Credentials Flow

Web-based application

Web-based applications are chosen when your application is used by multiple users and requires user intervention during authorization. For this client type, you must use redirection-based code generation. In this authorization flow,

• The user clicks the Login with Zoho button on any third-party web-based application.

• The application redirects the user to the Zoho Login page, and the user enters the Zoho credentials.

  

• A new pop-up, similar to the one below, appears to ask the user to choose the environment-specific organization, such as Production, Sandbox, or Developer, whose data the application can access. This applies only to applications with more than one organization.

  

• The user selects the organization for which the grant token has to be generated, and clicks Submit.

• The web application redirects the user to the Zoho OAuth server with the required scope in the Accounts URL:

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

  

  The page displays the chosen organization and the data (scope) that the application wants to access. Also, the request URL has the following parameters:

• scope: Scope limits the level of access the application has to access protected resources.Refer to Scopes for more details.

• client_id: Client ID(consumer key) that you obtained during client registration.

• response_type: This parameter is sent with value code

• access_type: Enter access_type as online or offline. If you want to generate the refresh token, set this value as offline.

• redirect_uri: The URI to which the authorization server will redirect the browser back with the authorization code. It must be the same URI provided when registering the app in the API console. It should start with http:// or https://. For example: https://www.zylker.com/oauthredirect

• Based on the user's login details, the system automatically detects the user's domain and uses the domain-specific authentication URL to obtain the organization-specific grant token (code).

• When the user clicks Accept: The application gets authorized. The organization-specific grant token is sent as a parameter in the redirect_uri.

  

• A back-end script from your end needs to store the following details from the above URL.

• code={grant_token} - This is used to generate access and refresh tokens.

• location={domain} - This tells you the domain of the user from which you have to make API calls.

• accounts-server={accounts_URL} - This is your accounts URL which you have to use to generate access and refresh tokens.

• The application exchanges the grant token for an access token.

• When the user clicks Reject: The browser redirects to the redirect URI with the parameter error=access_denied, and your application is denied access to the user's data in Zoho Service.

Note

• The grant token is valid only for two minutes. Refer to the Token Validity page for more details.
• The authorization URL has the scope for Users. You can change the scope as per your requirement.

Possible Errors

• ERROR_invalid_response_type

  Resolution: The value of the "response_type" key is not "code". Update the value as "code". (or) You have not passed the mandatory keys in the request. Pass all the mandatory keys in the request to generate the organization-specific grant token.

• ERROR_invalid_client

  Resolution: The client ID is wrong or empty. Pass the right client ID. You can check your client ID from the developer console.

• ERROR_invalid_redirect_uri

  Resolution: The redirect URI value passed, and the one registered in the developer console mismatches. Pass the right redirect URI.

• ERROR_invalid_scope

  Resolution: The scope is invalid. Pass valid scopes. You can refer to the list of scopes here.

Self-Client option

Use this method to generate the organization-specific 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 and log in with your Zoho Service username and password.

2. Choose Self Client from the list of client types, and click Create Now.

3. Click OK in the pop up to enable a self client for your account.

4. Now, your client ID and client secret are displayed under the Client Secret tab.

   

5. 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.

6. Select the Time Duration for which the grant token is valid. Please note that after this time, the grant token expires.

7. Enter a description and click Create.

   

8. A pop up displays the list of portals as shown below. Choose your portal. Further, the pop-up displays the list of environments and different organizations under each environment.

   

9. Select the organization in an environment you want to generate the grant token for, and click Create.

10. The organization-specific grant token code for the specified scope is displayed. Copy the grant token.

![](https://www.zohowebstatic.com/sites/zweb/images/crm/grant-token-self-client.png)

Note

• Generating the organization-specific grant token is a one-time process, provided you generate the access and refresh tokens within the time the grant token is valid for.

Generate Access Token and Refresh Token

OAuth2.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.

Note

• You must use your domain-specific Zoho accounts URL to generate access and refresh tokens. The following are the various domains and their corresponding accounts URLs.
  • For US: https://accounts.zoho.com
  • For AU: https://accounts.zoho.com.au
  • For EU: https://accounts.zoho.eu
  • For IN: https://accounts.zoho.in
  • For CN: https://accounts.zoho.com.cn
  • For JP: https://accounts.zoho.jp
  • For SA(Saudi Arabia): https://accounts.zoho.sa
  • For CA(Canada): https://accounts.zohocloud.ca
• If you have more than one organization, then the grant token generated will be specific to a particular organization, and the same applies to the access and refresh tokens generated using the grant token.

To generate access and refresh token:

1. Make a POST request with the following URL. Replace {accounts_URL} with your domain-specific Zoho accounts URL when you make the request.

   {accounts_URL}/oauth/v2/token

   Note: For security reasons, pass the below parameters in the body of your request as form-data.

   Request Parameters

   • grant_type

     Enter the value as "authorization_code".

   • client_id

     Specify client-id obtained from the connected app.

   • client_secret

     Specify client-secret obtained from the connected app.

   • redirect_uri

     Specify the Callback URL that you registered during the app registration.

   • code

     Enter the grant token you received after you made the authorization code request.

2. If the request is successful, you would receive the following:

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

   Response Parameters

   • access_token

     Access token to access ZService APIs.

   • refresh_token

     Refresh token to obtain new access tokens.

   • expires_in

     Time in seconds after which the access token expires.

   • api_domain

     Domain name of the API. Use this domain in your requests to make API calls to ZServices.

   • token_type

     Type of token obtained. "Bearer" indicates this is an access token.

This completes the authentication. Once your app receives the access token, send the token in your HTTP authorization header to ZService API with the value "Zoho-oauthtoken {access_token}" for each endpoint (for each request).

Note

• Each access token is valid for only an hour and can be used only for the operations defined in the scope.
• A refresh token does not expire. Use it to refresh access tokens when they expire. For more details on the validity of the tokens, refer to Token Validity page.
• Use the value in the "api_domain" key to make API calls to ZServices. The URL varies based on the environment:
  • For sandbox, the domain would be sandbox.zohoapis.{domain}. Example: https://sandbox.zohoapis.eu
  • For developer, the domain would be developer.zohoapis.{domain}. Example: https://developer.zohoapis.au
• If your application has more than one environment, the access and refresh token generated for a user becomes organization-specific in an environment. Thus, you cannot use tokens generated for an organization in one environment to make API calls to the organization in another environment. For instance, you cannot use tokens generated for an organization in the Production environment to make API calls to the organizations in the sandbox or developer accounts.

Possible Errors

• invalid_client

  Resolution: You have passed an invalid Client ID or secret. Specify the correct client ID and secret.
  (or)
  There is a domain mismatch. You have registered the client and generated the grant token in a certain domain (US), but generating the tokens from a different domain (EU). Ensure that you generate the grant, access, and refresh tokens from the same domain using the same domain URL or Enable Multi-DC for your client to generate tokens from any domain.
  (or)
  You have passed the wrong client secret when multi-DC is enabled. Each DC holds a unique client secret. Ensure to pass the right client secret for that DC.

• invalid_code

  Resolution: The grant token has expired. The grant token is valid only for one minute in the redirection-based flow. Generate the access and refresh tokens before the grant token expires.
  (or)
  You have already used the grant token. You can use the grant token only once.
  (or)
  The refresh token to generate a new access token is wrong or revoked. Specify the correct refresh token value while refreshing an access token.

• invalid_redirect_uri

  Resolution: The redirect URI in the request mismatches the one registered in the developer console. Specify the correct redirect URI in the request.

Refresh Access Token

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

• Make a POST request with the following URL:

  {Accounts_URL}/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token

  Note

  You must use your domain-specific Zoho Accounts URL to refresh your access token.

  • For US: https://accounts.zoho.com
  • For AU: https://accounts.zoho.com.au
  • For EU: https://accounts.zoho.eu
  • For IN: https://accounts.zoho.in
  • For CN: https://accounts.zoho.com.cn
  • For JP: https://accounts.zoho.jp
  • For CA(Canada): https://accounts.zohocloud.ca

• If the request is successful, you will receive the following output:

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

Note

• We have provided with a sample test OAuth in all the examples, so that you can test any example on your own. You can replace the sample OAuth Token with your actual token to test requests from your ZService account.
• For applications with multiple organizations, the refresh tokens generated for one organization in an environment cannot be used for another organization. For instance, you cannot use the refresh token generated for an organization in the Production environment to generate access tokens for the organizations in the sandbox or developer accounts.
• For information about the validity of the tokens, refer to the Token Validity page.

Revoking Refresh Token

If you want to revoke your refresh token,

• Make a POST request with the following URL:

  {Accounts_URL}/oauth/v2/token/revoke?token={refresh_token}

Note

• You must use your domain-specific Zoho Accounts URL to revoke your refresh token.See all the server-specific Account URLs.
• If you have multiple organizations, the refresh token that you revoke will be specific to a particular organization, and this action will not have an effect on other organizations in your application.

Client Credentials Flow

Compared to the flow of creating access tokens in the self-client flow, the client credentials flow can be used to perform one-time tasks like one-time data migration or testing ZService API calls, etc. We recommend using self client or server-based authorization for integration purposes. The main benefit of the client credentials flow is the simplicity in creating an access token, requiring only your client ID, client secret, scope, and soid.

Generating Access Token

To generate an access token using the client credentials flow, make an API call to the following endpoint with the mandatory parameters as discussed in the following "Parameters" section. The accounts-url is specific to the location (i.e., datacenter) where the client is registered. See all the server-specific URLs.

{accounts-url}/oauth/v2/token?client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials&scope={scope}&soid={soid}

Parameters

• client_idstring, mandatory

  Client ID (consumer key) that you obtained during client registration.

• client_secretstring, mandatory

  Client secret that you obtained during client registration.

• grant_typestring, mandatory

  Specify the value as "client_credentials".

• scopestring, mandatory

  The corresponding scope for the resource you want to access from the user's account. Multiple scopes can be given in comma separated format. Refer to the Scopes page for more details.

• soidstring, mandatory

  This parameter is derived from the unique ServiceOrg or organization or portal ID (zsoid).

  Syntax: ZService.{zsoid}. Example: ZService.600xxx46

  

  You can obtain zsoid from the UI by clicking on your profile picture where you will see the name of your organization. Click on the dropdown to view the name of the organization and the Org ID.

Response JSON

{
"access_token": "1000.b2caxxxxx3c6",
"scope": "ZService.org.ALL ZService.settings.ALL ZService.users.ALL ZService.templates.email.READ ZService.templates.inventory.READ ZService.modules.ALL",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}

• access_token

  Use this access token in the header of the API calls to access data in ZService. Note that the response does not contain a refresh token. When an access token expires, make an API call to the same endpoint to get a new access token (if required).

• scope

  The scope for the resource you want to access from the user's account that was provided in the parameters.

• api_domain

  Domain name of the API. Use this domain in your requests to make API calls to ZService.

• token_type

  Type of token obtained. "Bearer" indicates this is an access token.

• expires_in

  Time in seconds after which the access token expires.

Incremental Authorization

Incremental Authorization is an OAuth strategy that allows a client to request specific authorization scopes as and when needed. This means that the client does not have to request every possible scope that might be needed upfront, which might result in a bad user experience. Incremental Authorization is considered a best practice in Oauth Authorization Request as:

• Users are not overloaded with scopes in the initial stage
• Users can control the amount of data they share

For detailed information on implementing incremental authorization in your application, refer to the Zoho Accounts Incremental Authorization page.

Token Validity

Grant Token (Authorization code)

• Grant token is a one-time use token and valid for three minutes, by default. If you want to extend the expiry time, choose the required time from the drop-down while generating the token from the API console (applicable only to self-clients).
• You can generate a maximum of 10 grant tokens in a span of 10 minutes per client ID. If the limit is reached, "access_denied" exception will be thrown for the remaining time.

Access Token

• Each access token is valid for one hour.

• A maximum of 15 active access tokens can be stored per refresh token. When the 16th token is requested, the oldest token is invalidated. When an invalid access token is used, "INVALID_OAUTHTOKEN" exception will be thrown.

• You can generate a maximum of 10 access tokens from a refresh token in a span of 10 minutes.

• If the 10-minute throttle limit is reached, "Access Denied" error will be thrown. Reuse valid tokens to avoid this exception.

  {
  "error_description":"You have made too many requests continuously. Please try again after some time.",
  "error":"Access Denied",
  "status":"failure"
  }

Refresh Token

• Refresh tokens do not expire until a user revokes them.
• A maximum of 20 refresh tokens can be stored per user.
• When you generate the 21st refresh token, the first created refresh token gets invalidated.

API Collection

What is an API Collection?

The REST API Postman collection is a set of all the API requests. Using these boilerplate requests, you can test and explore the APIs in various environments for multiple organizations.

Why use API collection?

Going through the entire API documentation to set up environments, variables, authorization, and so on every time you need to test an API can be tedious. Using the API Postman collection can make the process of exploring APIs swift and effortless. It also significantly reduces the risk of errors.

Open API Specification (OAS)

Overview

An OpenAPI Specification (OAS) is a standardized way to describe RESTful APIs. It defines API structure, authentication methods, endpoints, request and response formats, in JSON or YAML.

Why use the Open API Specification ?

The Open API Specification is designed to provide:

• API Endpoints: The request URL and HTTP methods are specified, along with the optional and mandatory parameters required to make an API call request. The response formats for all possible HTTP response codes are available.
• Authorization: Supports OAuth authentication for secure access.
• Request and Response formats: Standardized request formats for GET, POST, PUT, and DELETE operations, detailed response schemas to explain returned data structures, and error handling guidelines to help developers debug API requests.