Introduction

The Patch Manager Plus 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 Patch Manager Plus modules, including SOM, Patch Management 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.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

OAuth 2.0 for APIs - An Overview

The PatchManagerPlusCloud 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 PatchManagerPlusCloud 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.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

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.PatchManagerPlusCloud 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, PatchManagerPlusCloud.SOM.READ

Here, PatchManagerPlusCloud is the service API name, SOM is the scope name, and READ 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 CREATE, READ, UPDATE, 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=PatchManagerPlusCloud.SOM.UPDATE,PatchManagerPlusCloud.SOM.READ&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 SOM module from the client PatchManagerPlusCloud account.

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

• scope=PatchManagerPlusCloud .SOM.READ(Read-only permission)
• scope=PatchManagerPlusCloud.PatchMgmt.READ
• scope=PatchManagerPlusCloud .SOM.UPDATE
• scope=PatchManagerPlusCloud.PatchMgmt.UPDATE

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,PatchManagerPlusCloud.SOM.READ,PatchManagerPlusCloud.PatchMgmt.READ.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

Register your Application

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

To register,

Go to Zoho Developer Console and click on GET STARTED.

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.

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.

• Server-based applications

  

• Client-based applications

  

• Self client

  

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

Possible Errors

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

Authorization Request

To use the PatchManagerPlusCloud 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 authorization code. The PatchManagerPlusCloud APIs use the authorization code grant type to provide access to protected resources.

There are two ways in which you can generate the authorization code based on the client type.

Self-client - Authorization code flow

Web-based application

Self-Client option

Use this method to generate the organization-specific authorization code 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.

• Go to Zoho Developer Console and log in with your PatchManagerPlusCloud username and password.

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

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

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

  

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

• Select the Time Duration for which the authorization code is valid. Please note that after this time, the authorization code expires.

• Enter a description

Click Create to generate < code>

Note

• Generating the authorization code is a one-time process, provided you generate the access and refresh tokens within the time the authorization code is valid for.

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.

  

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=PatchManagerPlusCloud.PatchMgmt.READ,PatchManagerPlusCloud.PatchMgmt.UPDATE&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}

The page displays the 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 authorization code.

When the user clicks Accept: The application gets authorized. The authorization code 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={authorization_code} - 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 authorization code 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 authorization code 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

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

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.

To generate access and refresh token:

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

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

This completes the authentication. Once your app receives the access token, send the token in your HTTP authorization header to DesktopCentralCloud 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.

Possible Errors

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

Managing OAuth Tokens

To manage your OAuth tokens after they have been generated, follow the processes below to refresh an expired access token and revoke a refresh token when necessary.

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

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

• 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"
          }

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}

• You must use your domain-specific Zoho accounts URL to revoke your refresh token.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

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.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

Token Validity

Authorization code

• Authorization code 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 authorization code 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 10active access tokens can be stored per refresh token. When the 11th 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" 
       }

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.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

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.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.

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.

© 2025, Zoho Corporation Pvt. Ltd. All Rights Reserved.