OAuth 2.0 User Guide

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. 

How does OAuth 2.0 work?

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

• The end user accesses the client application.
• The client application initiates authorization by sending a request for authorization code, mentioning the required scopes.
• The Zoho server prompts the end user to authorise the client application to access the end user's data within the mentioned scopes. 
• The end user authorizes the client application.
• The Zoho server sends the authorization code to the client application. 
• The client application requests the Zoho server for an access token, for the mentioned scopes, in exchange for the authorization code. 
• The Zoho server sends an access token ( and a refresh token, if requested). 
• 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.

Step-by-step guide to obtaining a Zoho-oauthtoken

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 (the end-user) or your client application should 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.

Query Parameters Details :

 * denotes mandatory parameter.

Step 3 : User authorization prompt

In response, the Zoho authentication server will prompt 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 window,  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 should request an access token from the Zoho authentication server by sending a POST request in any API platform like Postman, embedding the authorization code received in the previous step in the URL, along with other necessary details.

Query Parameter Details :

• denotes mandatory parameter.

Step 6 : Zoho server response

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

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 through Zoho Mail's APIs. 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. Therefore, the access token must be included in the Authorization header, prefixed with Zoho-oauthtoken, in every API request.

Renew Access Token

Access tokens have limited validity. In most cases, they expire in an hour. Once they expire, your client application 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.

Query Parameter Details:

• denotes mandatory parameter.

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

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.