OAuth 2.0 User Guide | Zoho Mail API

OAuth 2.0 Overview

Zoho Mail REST API uses OAuth 2.0 for secure authentication and authorization. OAuth 2.0 enables third-party applications to access resources without requiring the end user to repeatedly authenticate. By obtaining user consent, OAuth 2.0 allows applications to perform predefined API calls securely, ensuring data protection while enhancing user convenience.

If you're developing a custom application or customizing Zoho Mail features for specific business needs, OAuth 2.0 ensures secure access to Zoho Mail data through API integration.

Note:

In the context of this page, the client application refers to the third-party application that the user tries to access through the Zoho account and the End user refers to the user utilizing the client application.

Step-By-Step Guide to Obtaining a Zoho OAuth Token:

The following steps outline the OAuth 2.0 authentication flow for accessing Zoho Mail REST APIs:

Step 1 : Registering the Client Application

In this step, you (the end-user) need to register your client application in the Zoho Developer Console. You'll be required to provide a unique client name, a homepage URL, and a redirect URI. Once the registration is complete, a unique client ID and client secret will be generated for your application.

Follow the below steps for registering your client application:

Go to https://accounts.zoho.com/developerconsole.
Click on GET STARTED.
Choose the type of third-party client application that is being registered:
- Client-based Applications: Applications that run exclusively on a browser and are independent of a web server.
- Server-Based Applications: Applications that are clients running on a dedicated HTTP server.
- Mobile-based Applications: Applications that are installed on smartphones and tablets.
- Non-browser Mobile Applications: Applications for devices without browser provisioning such as smart TVs and printers.
- Self Client: Stand-alone applications that perform only back-end jobs (without any manual intervention) like data sync.
Enter the following requested details in the Zoho API Console's Create New Client page:
- Client Name: The name in which you register the client application with Zoho.
- Homepage URL: The URL of this client application's web page.
- Authorized Redirect URIs: A valid URL of the client application to which the Zoho authentication server responds to you with an authorization code after successful authentication.
Click CREATE. After successful registration, a unique Client ID and Client Secret specific to your application will be displayed in the Zoho API Console.

Step 2 : Requesting Authorization Code

You or the client application initiate the authorization process by requesting an authorization code through a GET request to the Zoho authentication server via a web browser. The request must include the required scopes, client_id, response_type, and redirect_uri.

Method:

GET

Sample Format of the URL to be called via a web browser:

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

Example Request:

https://accounts.zoho.com/oauth/v2/auth?client_id=1000.*****5&response_type=code&redirect_uri=https://zylker.com/redirect&scope=ZohoMail.accounts.READ&access_type=offline

Query Parameters Details :

Parameter	Type	Value	Description
*client_id	Unique Identifier	-	The ID that was assigned to the client application when registered.
*response_type	string	"code"	The type of response expected. In this case, "code" indicates an authorization code will be returned.
*redirect_uri	URI	-	The callback URI that was mentioned during the client application's registration.
*scope	string	Syntax: Servicename.scopename.Operation Example: ZohoMail.accounts.READ,ZohoMail.folders.UPDATE	Specifies the scope allowed for the client application. Has to be separated by commas. For detailed information on Scopes, click here.
access_type	string	"offline/online" (Default : "online")	Specifies whether a refresh token is required. "online" provides an access token only; "offline" provides both an access token and a refresh token.
prompt	string	"consent"	Add this parameter to reauthorize the user at each login, showing the consent screen every time. Use this parameter only when necessary.
state	string	-	A generated value that correlates the callback with its associated authorization request.

* denotes mandatory parameter.

Step 3 : User Authorization Prompt

In response, the Zoho authentication server prompts you (the end-user) to authorize the client application to access their data based on the specified scopes.

Step 4 : Granting Authorization

If you (the end-user) click "Accept" in the prompt, you authorize the client application to access your Zoho account's resources within the specified scope. Upon acceptance, the Zoho authentication server redirects you to the specified redirect_uri, including the requested authorization code "code" embedded in the URL.

Sample response format of the URL in which authorization code is received:
https://{redirect_uri}?code={authorization_code}&location={domain}&accounts-server={accounts_url}
Example response URL in which authorization code is received:
https://zylker.com/redirect?code=1000.*******77&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

The client application retrieves the authorization code from the above URL.
If the end user clicks Deny, the server will return an error.

Step 5: Exchanging Authorization Code for Access Token

The client application then requests an access token from the Zoho authentication server by sending a POST request in any API platform embedding the authorization code received in the previous step in the URL, along with other necessary details.

Method:

POST

Sample format of URL:

https://accounts.zoho.com/oauth/v2/token?code={authorization_code}&grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&scope={Servicename.Scopename.Operation}

Example URL:

https://accounts.zoho.com/oauth/v2/token?code=1000.****160&grant_type=authorization_code&client_id=1000.R2Z0W****Q5EN&client_secret=39c***921b&redirect_uri=https://zylker.com/redirect &scope=ZohoMail.accounts.READ

Query Parameter Details :

Parameter	Type	Value	Description
*code	string	-	The authorization code was obtained from the previous step.
*grant_type	string	"authorization_code"	Defines the type of grant being used. In this case, it's the authorization code grant type.
*client_id	Unique Identifier	-	The ID that was assigned to the client application when registered.
*client_secret	string	-	The client application's secret, which was assigned when it was registered.
*redirect_uri	URI	-	The callback URI that was mentioned during the client application's registration.
*scope	string	Syntax: Servicename.scopename.Operation Example: ZohoMail.accounts.READ	Specifies the scope allowed for the registered client application. Has to be separated by commas. For detailed information on Scopes, click here.
state	string	-	It has to be maintained the same during the entire process of authorization.

denotes mandatory parameter.

Step 6 : Zoho Server Response:

The Zoho server responds with an access token (and a refresh token if requested).

Sample Response Format:

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

Example Response:

{
"access_token": "1000.24a566***********6d276b472.86a1******883491c79a042af",
"refresh_token": "1000.f113ece**********82d02fb25e9.cc0**********8c57693baea39f",
"scope": "ZohoMail.accounts.READ",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}

You can store this data so that there is no need for authorization each time the end user accesses the registered client application. This completes the authentication.

Step 7 : Accessing Zoho Mail Resources

Once your client application obtains the access token, it can access Zoho's protected resources. When the access token is provided to the Zoho's resource server, your client application will be granted access based on the scopes specified in the request. Zoho's OAuth implementation uses the Bearer authentication scheme, so the access token must be included in the Authorization header, prefixed with the Zoho-oauthtoken.

Access Token Renewal

Access tokens have limited validity. In most cases, they expire in an hour. Once they expire, your app will have to use the refresh token to request a new access token for further use. This process repeats every time the access token expires, ensuring that the refresh token is consistently used to obtain a new access token. This cycle continues until access is explicitly revoked.

The client application requests that the Zoho authentication server renew the access token by sending a POST request to the API platform, embedding the refresh token received in step 6 in the URL, along with other necessary details.

Method:

POST

Sample Request format of URL:

https://accounts.zoho.com/oauth/v2/token?refresh_token={refresh_token}&grant_type=refresh_token&client_id={client_id}&client_secret={client_secret}

Example URL :

https://accounts.zoho.com/oauth/v2/token ?refresh_token=1000.4069dacb56*****36&grant_type=refresh_token&client_id=1000.R2Z0W***Q5EN&client_secret=39c****921b

Query Parameter Details:

Parameter	Type	Value	Description
*refresh_token	string	-	The authorization code was obtained from the previous step.
*grant_type	string	"refresh_token"	Defines the type of grant being used. In this case, it's the refresh token grant type.
*client_id	Unique Identifier	-	The ID that was assigned to the client application when registered.
*client_secret	string	-	The client application's secret, which was assigned when it was registered.
scope	string	Syntax: Servicename.scopename.Operation Example: ZohoMail.accounts.READ, ZohoMail.folders.UPDATE	Specifies the scope allowed for the registered client application. Has to be separated by commas. For detailed information on Scopes, click here.
state	string	-	It has to be maintained the same during the entire process of authorization.

denotes mandatory parameter.

If the request is successful, you will receive the following response:

Sample response format:

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

In response, you have received a new Access Token. This new Access Token will also have an hour of time validity.

Revoke Refresh Token

Access tokens are revoked on logout, expiration, security updates, suspicious activity, or account changes to maintain security.

The client application requests that the Zoho authentication server revoke the refresh token by sending a POST request to the API platform, embedding the refresh token received in step 6 in the URL, along with other necessary details.

Method:

POST

Sample Request format of URL:

https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}

Example URL:

https://accounts.zoho.com/oauth/v2/token/revoke?token=1000.4069dacb56*****3677

Note:

Some APIs require Admin authentication for execution, while others can be executed with user authentication. Certain APIs are designed to be executed by both Admins and Users. However, the request URLs will differ based on the user's role.