OAuth 2.0 User Guide

Zoho Mail Rest API uses the OAuth 2.0 protocol for authentication and authorization. OAuth 2.0 is the standard authentication framework that enables third-party applications to gain secure access to application resources, without having to authenticate every time. It provides a secure channel for third-party application developers to create and implement features and functions in their customised applications enabling end users to access server resources through predefined API calls. 

Suppose you intend to develop a custom application with a Zoho account or customize existing Zoho Mail features to meet specific requirements. In that case, the first step is to obtain permission from the end user to access their data via Zoho Mail API. When using OAuth 2.0, the end user must authorize the third-party application to securely access their Zoho Mail data.

How does OAuth work?

The following steps will help you understand the OAuth 2.0 authentication process:

1. The end user accesses the client application.
2. The client application initiates authorization by sending a request for authorization code, mentioning the required scopes.
3. The Zoho server prompts the end user to authorise the client application to access the end user's data within the mentioned scopes. 
4. The end user authorizes the client application.
5. The Zoho server sends the authorization code to the client application. 
6. The client application requests the Zoho server for an access token, for the mentioned scopes, in exchange for the authorization code. 
7. The Zoho server sends an access token ( and a refresh token, if requested). 
8. The client application uses the access token to access resources on behalf of the end user from the Zoho server. If the access token expires, the refresh token is used to obtain a new access token, allowing the client application to continue accessing resources seamlessly. 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 following steps will help you understand, how to proceed with the OAuth 2.0 authentication process.

1. Registering the client application : Generating Client ID and Client Secret

The initial step in using OAuth authentication is registering the client application with the Zoho API console. Once the client application is registered, you will get a Client ID and Client secret for the application. This Client ID and Client secret, is used to authorize the client application's OAuth requests.

To register,

• Go to the Zoho Developer Console.
• In the Zoho API Console page, 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. 
    For more details, refer here.
• Enter the following details: 
  • Client Name: The name of the client application you want to register with Zoho.
  • Homepage URL: The URL of the client application's web page.
  • Authorized Redirect URIs: A valid URL of the client application to which Zoho Accounts redirects you with an authorization code after successful authentication.
    
• Click CREATE. 
  

You will be provided with the Client ID and the Client secret. Using these credentials, you can go ahead with the OAuth 2.0 authentication. 

2. Generating Authorization Code

The next step is to obtain an authorization code. For this, you will have to call the following Authorization URL with the mentioned query parameters.

Query Parameters:

* Mandatory parameters

Once this Authorization URI is called, the end user is shown a User consent page, that asks for the permission of the end user to access the Zoho Mail resources within the mentioned scope.

If the end user clicks Accept, Zoho calls the redirect URI mentioned during the client application registration, with the authorization code. 

Example:

https://zylker.com/oauth2callback?code=1000.******************.*********77&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

Description:

• code={authorization_code} - This will be used to generate access and refresh tokens. The Authorization code is valid only for two minutes.
• location={domain} - This specifies the end user's domain from which API calls should be made. Based on the end user's login details, the system automatically detects the end user's domain and uses the domain-specific authentication URL to obtain the organization-specific authentication code.
• accounts-server={accounts_URL} - This is the accounts URL that you have to use to generate access and refresh tokens.

If the end user clicks Deny, then the server returns an error.

Prompting re-consent: 

You can request the end user to reauthorize your app each time they log in by adding the prompt=consent parameter to the authentication request. When prompt=consent is included, the consent screen is displayed during every login. Include prompt=consent only when necessary.
 

3. Generating Access Token : In exchange for the Authorization Code, Get Access and Refresh Token

Zoho's OAuth implementation uses the Bearer authentication scheme. Hence, while making API calls, the access token has to be passed in the Authorization header with the prefix Zoho-oauthtoken. 

To generate an access and refresh token, make a POST request with the following URI.

Query Parameters

*Mandatory parameters

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

Description:

• access_token - Access token to access Zoho Mail APIs.
• refresh_token - Refresh token to generate new access tokens.
• api_domain - Domain name of the API. Use this domain in your requests to make API calls to Zoho Mail.
• expires_in - Time in seconds after which the access token expires.
• token_type - Type of token. ("bearer")

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.

4. Use the Access Token : Access Zoho Mail REST APIs with the Access Token

Once the client application receives the access token, to call Zoho Mail REST APIs, send the access token in your HTTP Authorization header to Zoho Mail API with the value 
Zoho-oauthtoken<space>{access_token} for each endpoint (for each request).

When this Access Token with the available scopes invokes the URI, the information as permitted in the scope is granted to the client application. Here, in this sample request, the client calls an API that retrieves the list of Zoho mail accounts of the currently authenticated end user. 

Refreshing the Access Token

Access tokens have limited validity. In most cases, the access tokens will expire in an hour. Once it expires, 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.

To obtain a new access token, make a POST request to the following URL:

Query Parameters

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

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