OAuth 2.0 Token

Zoho Mail REST API supports the OAuth 2.0 protocol to authorize and authenticate API requests. OAuth 2.0 is the standard authentication protocol that allows third-party application developers to allow their users to securely access and use the server resources without having to authenticate each time. Ensure that you have the permission to access API service. If not, please contact support@zohomail.com.

OAuth 2.0 Overview

In OAuth 2.0, the user can authorize a third-party application to use Zoho Mail resources related to that particular user in a secure manner. 

Step 1: A user wants to use a third-party application/ integration to access or automate Zoho Mail. 

Step 2: The third party app connects with Zoho Mail and requests a token on behalf of the user using this API.

Step 3: Zoho Mail provides a temporary token and a secret code to the third-party app. The secret code is to prevent any forgery and for the server to identify the application from which the requests come in. 

Step 4: The app redirects the user to Zoho Mail along with the temporary token and the secret code. In Zoho Mail, the user sees a prompt to Authorize the third-party app to access his account and data. 

Step 5: The user authorizes the third party app. At this point, the third party app provides the temporary token along with the secret code and gets a Permanent Access Token using this API. 

Step 6: All the future actions of the user through the app will be done via the Access Token and the Secret code

Third-Party app - Get Client ID and Client Secret:

You need to register the app with the Zoho Developer console to get the Client ID and Client Secret.  To register your application, follow the instructions below: 

  1. Navigate to the Zoho Developer Console.
  2. In API Credentials page, click on Add Client ID to create a new Client ID and Client Secret. 
  3. Provide the Client Name, Client Domain and the Authorized redirect URIs. (The redirect URI is the callback entry point of the app and is different from the entry point of the app.)
  4. You will get a set of OAuth 2.0 details with the Client ID and Client Secret shared only between Zoho and the application.

Getting Authorization

Next, you will have to call the Authorization URI - https://accounts.zoho.com/oauth/v2/auth 

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

The Authorization URI should contain the following parameters as a query string:

Parameter

Type

Description

*client_id

Unique Identifier

The ID that was assigned to your app when you registered it.

*response_type

string

"code"

*redirect_uri

URI

Your callback URI which you used during registration.

*scope

string

Specifies the scope allowed for your app. Has to be separated by commas.
Syntax: 
Servicename.scopename.Operation
Example: ZohoMail.folders.READ, ZohoMail.folders.CREATE

access_type

string

offline/online (Default value: 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.

prompt

string

prompt=consent.
Prompts for user consent each time your app tries to access user credentials.

state

string

A generated value that correlates the callback with its associated authorization request.

*Mandatory parameters

Scope Names and Operations

API Name

Scope Name

Operation

Accounts

accounts

READ, UPDATE

Organization

partner.organization

Organization Subscriptions

organization.subscriptions

Organization Spam

organization.spam

READ

Organization Account Management

organization.accounts

READ, CREATE, UPDATE

Messages

messages

CREATE, READ, UPDATE, DELETE

Attachments

attachments

Groups

organization.groups

Labels

tags

Folders

folders

Domains

organization.domains

Example

GET oauth/v2/auth 
Host:: https://accounts.zoho.com

Query String:

https://accounts.zoho.com/oauth/v2/auth
?response_type=code 
&client_id=1000.R2*************************5EN
&scope=ZohoMail.folders.READ
&redirect_uri=https://zylkerapps.com/oauth2callback
&state=-54****************5

Once this Authorization URI is called, the user is shown a 'User consent page'.

If the user clicks Accept, Zoho redirects the user back to your site with an 'Authorization code'. Your application can now request Zoho for an Access Token using the auth_code. If the user clicks Deny then the server returns an error.

Prompting re-consent

You can prompt the user to re-authorize your app every time the user logs in by adding the prompt=consent parameter to the authentication request. When prompt=consent is included, the consent screen is displayed while the user logs into your app. For this reason, include prompt=consent only when necessary. 

Note: The prompt=consent parameter is mandatory while fetching the Refresh Token.

Getting the Access Token

Once your application receives the Authorization code, a new request can be made to receive an Access Token using which your app will receive the user credentials. As this is an important step in the entire process, please be careful while setting the parameters for the same. 

Parameter

Type

Description

*code

string

Authorization code obtained from the initial request.

*client_id

Unique Identifier

The ID that was assigned to your app when you registered it.

*client_secret

string

Your app's secret. Assigned when you register your app, which is available in your profile.

*redirect_uri

URI

Your callback URI as given during the time of application registration.

*scope

string

Specifies the scope allowed for your app. Has to be separated by commas.

*state

string

Has to be maintained the same during the entire process of authorization.

grant_type

string

"authorization_code"

*Mandatory parameters

Response

Once the request along with the Authorization code is sent, Zoho will issue a response to your app which will give you the following information.

  • expires_in - Time in milliseconds for which the token remains valid.
  • token_type - Type of token. ("bearer")
  • access_token - Access Token for the user. This token can be used for the final API calls and will be valid only for an hour.
  • refresh_token - Refresh Token to use when the Access Token has timed out. This token is permanent and can be used multiple times to refresh the app and get a new Access Token.

You can store this data so that there is no need for authorization each time this user accesses your app.

Example

POST oauth/v2/token
HOST:: https://accounts.zoho.com

Query String:

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

Using the Access Token

Send the Access Token as a header when you call a Zoho Mail REST API.

Example

GET oauth/user/info

Query String:

GET
HOST: https://accounts.zoho.com/
Header:
Authorization= Zoho-oauthtoken <space> <access token>

When this Access Token with the available scopes invokes the URI, the info as permitted in the scope is granted to the application. The user credentials are thus obtained and the regular signup flow can be implemented.

Access Token Expiry

In your request for access, you can request a Refresh Token to be returned along with the Access Token. A Refresh Token allows Rest APIs access your applications even when the user is not logged in. To request a Refresh Token, add access_type=offline to the authentication request.

The Refresh Token will always be generated by the prompt=consent. The maximum number of Refresh Tokens is 20. Once the limit is reached, the first Refresh Token generated will be deleted.

The Access Tokens have limited validity. In most 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.

For this new request, the parameters to be included are:

Parameter

Type

Description

client_id

Unique Identifier

The ID that was assigned to your app when you registered it.

client_secret

string

Your app's secret.

Assigned when you register your app and available in your profile.

grant_type

string

refresh_token

redirect_uri

URI

Your callback URI.

refresh_token

string

The Refresh Token provided along with the Access Token.

 

Example

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

HOST:: https://accounts.zoho.com

Query String:

?refresh_token=1000.4069dacb56****************************************bcf902062390367
&grant_type=refresh_token
&client_id=1000.R2Z0W*********************Q5EN
&client_secret=39c**********************************921b
&redirect_uri=https://zylkerapps.com/oauth2callback
&scope=ZohoMail.folders.UPDATE

You will now receive a new Access Token using which you can continue getting user credentials. This Access Token will also have a time limit of one hour.

Some APIs need an Admin authentication to be executed, and some APIs will be executed only with a user authentication. There are certain APIs that can be executed both by the Admin and the User. But, the request URLs will differ according to the role.

Note:

We don't support AuthToken anymore. Please make use of OAuth 2.0. To know more about why we have moved to OAuth 2.0, visit this help page.