OAuth 2.0 Authentication

Overview

OAuth 2.0 is a token based authorization framework that enables limited access to the third-party application. OAuth acts as an intermediary on behalf of the user and provides controlled access, i.e. access only to the resources authenticated by the user and blocking the rest. This strengthens the security and also user data compromise is minimal.

How does it work?

Steve, a client of Zoho, owns a third-party application (say Zylker). Helen, the end user who uses Zylker, wants to gain access to some of the protected data in Zoho. Let's help Helen to access the data.

1. Steve registers Zylker with Zoho Developer Console. Upon successful registration, a Client ID and a Client Secret is generated.
2. Helen raises a request to access the protected resources of Zoho via Zylker. 
3. Helen will be asked for consent so that Zylker can access her data via Zoho Projects API.
4. If Helen clicks Accept, she will be redirected to the URL (Redirect URL) mentioned while registering the application. 
   • The authorization code is embedded in the URL.
5. The authorization code is exchanged to obtain Access and Refresh tokens.
6. Helen can make requests to the API with the access token for the next hour. 
7. Once the access token expires, it can be regenerated using the refresh token.
8. The controlled access can be revoked anytime if Helen faces any security breach or if the access is no longer needed.

OAuth2.0 Authentication

Learn the steps to access Zoho Projects' API using OAuth 2.0 authentication.

• Register your application
• User authorization request
• Generate access and refresh tokens
• Regenerate access token
• Revoke refresh token
• Use APIs with the access token

Register your application with Zoho Developer Console

1. Go to https://accounts.zoho.com/developerconsole.
2. Click Add Client ID.

Note: Enter the URL based on your DC.          

EU - accounts.zoho.eu
IN - accounts.zoho.in
AU - accounts.zoho.com.au
CN - accounts.zoho.com.cn
JP - accounts.zoho.jp

3. Enter the client name, domain, and callback(redirect) URI.
   1. Client Name is the name of your application.
   2. Client Domain is your URL to access the application.
   3. Redirect URI is the callback URL of your application to which the user will be redirected upon successful authorization. The server returns a code parameter as a query string in the redirect URL. This code is used to obtain access and refresh tokens.
4. Click Create.

5. On successful registration, you will be provided with Client ID and Client Secret. Note the client credentials to generate authorization code.

 User authorization request

1. Enter the authorization URL  along with values of the below parameters as a query string.

Parameters

scope	Specifies the scope restriction of your application. The scope of each API is mentioned in the particular module (ZohoProjects.<module>.<operation>). Multiple scopes are separated using commas. Example: ZohoProjects.tasks.READ, ZohoProjects.projects.ALL.
client ID	Enter the Client ID generated while registering the application.
response_type	Specify the response_type value as code.
access_type	Specify as online or offline. Offline access type generates both access and refresh tokens. Online access type provides only access token.
redirect_uri	Redirect URI is the callback URL mentioned while registering the application.
prompt	Specify the prompt value as consent. The server prompts the user for consent every time before generating an authorization code. If consent is required only once then specify the value as none.

2. User will be prompted for consent in user authorization page.
3. Click Accept.

4. On successful authorization, a code parameter is generated in the redirect URI.
5. This code is valid for two minutes and it is used to obtain access and refresh token. 

Sample Request

Sample Response

 Generate access and refresh token

The final step to access Zoho Projects' APIs is to authenticate with an access token. The authorization code can be exchanged to get the access and refresh token.

Note: This code can be exchanged only once. If the code expires then it has to be regenerated.

1. Make a POST request with the below URL along with the parameters as a query string.

Parameters

code	Specify the authorization code. Note: This code is valid only for two mins. Regenerate a fresh code if it expires.
redirect_uri	Redirect URI is the callback URL mentioned while registering the application.
client_id	Specify the Client ID generated while registering the application.
client_secret	Specify the Client Secret generated while registering the application.
grant_type	Specify grant_type value as authorization_code

Sample Request

Sample Response

2. Use this access token for future requests for the next one hour.
3. Refresh token is used to fetch new access token when the current one expires.
4. Refresh token is permanent and can be used to get a new access token.

Note: Creating an access token using a code is typically a one-time process. Use the refresh token to generate the access token to automatically sync your services.

 Regenerate access token

The access token is valid for one hour. As long as the application is authorized, the refresh token can be used to exchange for a new access token.

1. Make a POST request along with the values of the below parameters as a query string.

Parameters

refresh_token	Enter the refresh token.
client_id	Enter the Client ID generated while registering the application.
client_secret	Enter the Client Secret generated while registering the application.
grant_type	Specify grant_type value as refresh_token.

Sample Request

Sample Response

 Revoke refresh token

If the end user no longer requires to access the application, they can revoke their access.

1. Enter the following URL to revoke refresh_token using the POST method

Sample Request

Sample Response

Use APIs with the access token

Let us consider an example (Get all portals) API  and make a request with the access token.

1. Use the GET method and enter the below URL.

2. Navigate to Headers section and provide the Key values as below

Authorization

Bearer or Zoho-oauthtoken<space><Access token>.

 

Sample Response:

 

      For common user queries on this topic please refer to the FAQ section.