Getting Started (For Cloud)

Patch Manager Plus now facilitates easy integration with your existing infrastructure using REST APIs. You can perform various patching activities easily from a single console. You can find the list of modules for which APIs are available in the sidebar, if you need more APIs you can contact us with your requirement.

This document describes the prerequisites for using the API.

Multiple data centers

Patch manager plus cloud is hosted at multiple data centers, and therefore available on different domains. There are 7 different domains for Patch manager plus cloud APIs, so you can use the one that is applicable to you.

The APIs on this page are intended for organizations hosted on the .com domain. If your organization is on a different domain, replace ".com" with the appropriate domain for the API endpoints before using them.

Note: You can find out which domain you're accessing by checking the URL while accessing Patch Manager Plus.

Authentication

Patch manager plus REST API supports OAuth 2.0 protocol to authorize and authenticate API calls. Follow the steps listed here to use OAuth 2.0 protocol in Patch manager plus APIs.

OAuth Token Generation

The steps to generate an OAuth token are as follows:

1. 1. Generate <Client ID> and <Client Secret>
2. 2. Authorization by generating the <grant token>
3. 3. Generating <Access> and <Refresh Token>
4. 4. Generate <Access Token> from <Refresh Token>

Step 1: Generate Client ID and Client Secret

1. 1. Register your application as a new client by accessing the respective DeveloperConsole from the above table.
2. 2. Choose <Client Type> that suits your application type.



3. 3. After choosing the client type, provide the required details and click 'Create'.

On successful registration, you will be provided with a set of OAuth 2.0 credentials such as <Client_ID> and <Client_Secret> that will be only known to Zoho and your application. (Do not share this credentials anywhere)

Step 2: Authorization by generating the grant token

After generating <Client_ID> and <Client_Secret>, a grant code has to be generated. Based on the client type the code can be generated in two ways.

1. i. Self Client Method - For Self Client type.
2. ii. Redirect Method - For Server-based Applications.

Self Client Method

• - After registration, click the <Self Client> method available on the Applications list.
• - Enter a valid <scope>. (Refer Scopes for more details.)
• - Choose Time Duration.

NOTE: The grant<Code> value generated in this step will be expired after this period. The <Refresh Token> (Step 3) needs to be generated before the code expires.

• - Enter <Scope> Description.



• - Click Create to generate < code>

Redirect Method (For server based applications)

Make a request to the below URI with the given parameters,

https://<ZohoAccounts_Server_URI>/oauth/v2/auth?scope=<SCOPE>&client_id=<CLIENT_ID>&state=testing&response_type=code&redirect_uri=<REDIRECT_URI>&access_type=offline&prompt=consent

Note: Fields with * are mandatory

Example

https://accounts.zoho.com/oauth/v2/auth?scope=PatchManagerPlusCloud.Common.READ&client_id=1000.I******************YF&state=54************5&response_type=code&redirect_uri=https://zylkerapps.com/oauth2callback&access_type=offline&prompt=consent

On invoking this request, If you already signed in with Zoho then a user consent page will be shown, If you do not have an active login session with Zoho then you will be redirected to the Zoho login page, and you need to enter your Zoho credentials to login. After authentication, the user consent page will be shown.

• 1. On clicking Accept, the application gets authorized. The grant <code> is sent as a parameter in the redirect_uri.
• 2. 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 refresh and access tokens.

Note: This code is valid for only 60 seconds. Next Step have to be done within this time.

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 Patch manager plus.

Step 3: Generating Access and Refresh Token

Access Token

An access token is sent to the resource server to access the protected resources of the user. The <Access token> provides secure and temporary access to Patch Manager Plus 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 are described in the scope.

Refresh Token

A refresh token is used to obtain new <access tokens>. This token has an unlimited lifetime until it is revoked by the end user.

After generating the Authorization code, a POST request is to be made for the following URI with the params given below, to generate <refresh_token> and <access_token>.

METHOD: POST

https://<ZohoAccounts_Server_URI>/oauth/v2/token?code=<CODE>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&redirect_uri=<REDIRECT_URI>&grant_type=authorization_code

Note: Fields with * are mandatory

EXAMPLE

METHOD: POST

https://accounts.zoho.com/oauth/v2/token?code=1000*********************e95e&client_id=1000.I*****************6YF&client_secret=1b****************96&redirect_uri=https://zylkerapps.com/oauth2callback&grant_type=authorization_code

• In response, you will get both <access_token> and <refresh_token>.
• 
• 1. The <access_token> will expire after an hour.
• 2. The <refresh_token> is permanent and will be used to regenerate new <access_token>, if the current access token expires.

NOTE: Each time a re-consent page is accepted, a new <refresh token> is generated. The maximum limit is 20 <refresh tokens> per user. If this limit is crossed, the first <refresh token> is automatically deleted to accommodate the latest one. This is done irrespective of whether the first refresh token is in use or not.

Step 4: Generating the access token from refresh token

<access_tokens> have limited validity. It expires in one hour. Once the <access_token> expires, the user (or) the app will have to use the <refresh_token> to request for a new <access_token>. Using an expired access token throws the Invalid Oauthtoken error.

You can request for a refresh token to be generated along with the access token. To request a refresh token, add access_type=offline in the request for generating the grant token. (Refer Step 2).

The <refresh_token> will always be generated by giving the parameter: prompt=consent

Note: Using a <refresh_token> client can create up to ten access tokens in ten minutes. If the limit is reached, the access token creation will be blocked for the rest of the ten minutes.

The following POST URI with the params given below, generates a new <access_token>.

METHOD: POST

https://<ZohoAccounts_Server_URI>/oauth/v2/token?refresh_token=<REFRESH_TOKEN>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&redirect_uri=<REDIRECT_URI>&grant_type=refresh_token

EXAMPLE

METHOD: POST

https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.1*********************fb8&client_id=1000.I**********************6YF&client_secret=1b******************************96&redirect_uri=https://zylkerapps.com/oauth2callback&grant_type=refresh_token

In response, you will get a new <access_token>

CALLING AN API USING OAUTH AUTHENTICATION

API - URI Structure

All API URI must be structured in the following format,

<PatchManagerPlus_Server_URI>/api/{Version}/{Entity}/{Operation|Action}

<access_token> can be passed only in header and cannot be passed in the request param.

• Header name = Authorization
• Header value> = Zoho-oauthtoken<space><access_token>
• Sample: Authorization: Zoho-oauthtoken 1000.abcde12345fgh678.ijk9

Example of calling the SOM Summary API in postman

Request URI: https://patch.manageengine.com

API URI: api/1.4/som/summary

METHOD: GET

SCOPE