OAuth

In case of MDM Cloud Zoho REST APIs are used, where the authorization and authentication done using OAuth 2.0. It provides secure access to protect resources thereby reducing the hassle of asking for a username and password every time a user logs in. Follow the steps listed here, to access Zoho’s APIs using OAuth 2.0

For more details, refer OAuth Overview.

Scope

Manageengine's MDM 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 devices, or to view profiles 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

Example:
MDMOnDemand.MDMDeviceMgmt.ALL
Here, MDMOnDemand is the service API name, MDMDeviceMgmt is the scope name, and ALL is the operation type.

Available Scopes

Inventory

To access inventory related APIs

• MDMOnDemand.MDMInventory.CREATE
• MDMOnDemand.MDMInventory.UPDATE
• MDMOnDemand.MDMInventory.READ
• MDMOnDemand.MDMInventory.DELETE
• MDMOnDemand.MDMInventory.ALL

Device Management

To access profiles, apps, groups and user_groups related APIs

• MDMOnDemand.MDMDeviceMgmt.CREATE
• MDMOnDemand.MDMDeviceMgmt.UPDATE
• MDMOnDemand.MDMDeviceMgmt.READ
• MDMOnDemand.MDMDeviceMgmt.DELETE
• MDMOnDemand.MDMDeviceMgmt.ALL

User

To manage users assign to device

• MDMOnDemand.MDMUser.CREATE
• MDMOnDemand.MDMUser.UPDATE
• MDMOnDemand.MDMUser.READ
• MDMOnDemand.MDMUser.DELETE
• MDMOnDemand.MDMUser.ALL

Step 1: Registering a Client

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

To register,

• Login to Zoho Developer's Console
• Choose a client type which is listed below
1. Client-based Applications
   Applications that run exclusively on a browser and are independent of web servers.
2. 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.
3. Mobile-based Applications
   Applications that are built to run on smart phones and tablets.
4. Non-browser Mobile Applications
   Applications that run on devices without browsers such as smart TVs and printers.
5. 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.

On successful registration, you will be provided with a set of OAuth 2.0 credentials such as a Client ID and Client Secret , known to both Zoho and your application. Do not share this credentials

Step 2: Generating Grant Token

For Server-based Applications

Redirect to the following authorization URL with the given params

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

Parameter	Description
scope *	SCOPE for which the token to be generated. Multiple scopes can be given which has to be separated by commas. Ex : MDMOnDemand.MDMInventory.CREATE
client_id *	Client ID obtained during Client Registration
state	An opaque string that is round-tripped in the protocol; ie., whatever value given to this will be passed back to you.
response_type *	code
redirect_uri *	One of the redirect URI given in above step. This param should be same redirect url mentioned while registering the Client
access_type	The allowed values are offline and 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. By default it is taken as online
prompt	Prompts for user consent each time your app tries to access user credentials. Ex: Consent

Note: Fields marked with * are mandatory

On this request, you will be shown with a "user consent page".

Upon clicking “Accept”, Zoho will redirect to the given redirect_uri with code and state param. This code value is mandatory to get the access token in the next step and this code is valid for 60 seconds.

On clicking “Deny”, the server returns an error

For Self-Client

To Generate code for Self-Client

1. Go to Zoho Developer's Console.
2. Click on Self Client and navigate to Generate Code tab.
3. Provide Scope, Time Duration followed by Scope Description.
4. Click on CREATE. Copy or download the generated CODE which will be needed for Generation of Access and Refresh token

Step 3: Generate Access and Refresh Token

After getting code from the above step, make a POST request for the following URL with given params, to generate the access_token.

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

Parameter	Description
code *	code which is obtained in the above step
client_id *	Client ID obtained during Client Registration
client_secret *	Client secret obtained during Client Registration
redirect_uri *	This param should be same redirect url mentioned while adding Client.Won't needed for Self Client.
grant_type *	authorization_code
scope	SCOPE for which token to be generated. Ex : MDMOnDemand.MDMInventory.CREATE. Multiple scopes has to be separated by commas.
state	An opaque string that is round-tripped in the protocol; that is to say, value will be passed back to you.

Note: Fields with * are mandatory

In the response, you will get both access_token and refresh_token.

1. The access_token will expire after a particular period (as given in expires_in param in the response).

2. The refresh_token is permanent and will be used to regenerate new access_token, if the current access token is expired.

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: Generate Access Token From Refresh Token

Access Tokens have limited validity. In most general 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. Redirect to the following POST URL with the given params to get a new access token

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

Parameter	Description
refresh_token	REFRESH TOKEN which is obtained in the above step
client_id	Client ID obtained during Client Registration
client_secret	Client secret obtained during Client Registration
redirect_uri	This param should be same redirect url mentioned while registering Client
grant_type	refresh_token

Step 5: Revoking a Refresh Token

To revoke a refresh token, call the following POST URL with the given params

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

Parameter	Description
refresh_token	REFRESH TOKEN which is to be revoked

Step 6: Calling An API

Access Token can be passed only in header and cannot be passed in the request param.

• Header name should be Authorization
• Header value should be Zoho-oauthtoken {access_token}

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 two 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 developer console (applicable only to self-clients).
• You can generate a maximum of 10 grant tokens in a span of 10 minutes per client ID.

Access Token

• Each access token is valid for one hour.

Refresh Token

• Refresh tokens do not expire until a user revokes them.
• You can generate a maximum of 10 access tokens from a refresh token in a span of 10 minutes.
• You can generate a maximum of 20 refresh tokens in a span of 10 minutes per client ID.
• When you generate the 21st refresh token, the first created refresh token gets deleted.

Errors

In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicate server side errors. Commonly used HTTP status codes are listed below.

HTTP Status Codes

Status Code	Descriptions
2xx	Success
4xx	Bad request sent to server
5xx	Server side error

Status Code	Description
200	Success The request was successfully completed.
201	Created The request was a success and one or more resources have been created.
400	Bad request The request cannot be performed. Usually because of malformed parameter or missing parameter.
401	Unauthorized (Invalid AuthToken) Request was rejected because of invalid AuthToken.
403	Forbidden The user does not have enough permission or possibly not an user of the respective organization to access the resource.
404	URL Not Found The URL you’ve sent is wrong. It’s possible that the resource you’ve requested has been moved to another URL.
405	Method Not Allowed The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
406	Not Acceptable The requested response type is not supported by the client.
429	Too many requests Too many requests within a certain time frame.
500	Server errorA Server error has occurred.

Common Error codes

The error codes returned by the server is listed below.

Error Code	HTTP status	Error Description
COM0001	405	Method not implemented / Invalid URL
COM0002	429	API Limit Exceeded
COM0003	400	Invalid paging params
COM0004	500	Internal server error, Please try again in a moment
COM0005	400	Parameters in post were invalid or missing
COM0006	400	No request data recieved
COM0007	412	Assist is not Integrated.
COM0008	404	Unknown Resource
COM0009	422	Insufficient Data for Processing Request
COM0010	409	Resource Already Exists
COM0011	422	Invalid / Missing headers
COM0012	400	Invalid API version
COM0013	401	Not Authorised/ Invalid auth token
COM0014	400	Bad Request
LOC0001	412	Location Fetch error
SDE0003	412	Assign User failed
CMD0001	412	Command not applicable for Device
CMD0002	412	Unable to suspend command
APP0001	400	App Upload Regected
APP0002	412	Unable to delete app or profile
COM00020	400	Device license limit reached
FIL0001	400	File upload rejected
COM0015	412	Precondition Failed
COM0021	400	Invalid delta token
PAY0001	400	The image uploaded must be less than the size specified!
PAY0002	400	Specify all the requisite fields to proceed further!
PAY0004	400	Verify the values specified for the requisite fields!