OAuth2.0 Authentication
Zoho Projects API uses OAuth 2.0 protocol for authentication and authorization. OAuth 2.0 is an authorization framework that lets your application access Zoho Projects API on behalf of a user without your application having access to the login credentials. This document will help you access and manage a user's data in Zoho Projects with APIs.
- Register Your Application
- User Authorization Request
- Generate Access and Refresh Token
- Regenerate Access Tokens
- Revoking Tokens
- Using Access Token in API
Register Your Application
Register your application with Zoho Projects API to receive a client ID and client secret.
- Navigate to: https://accounts.zoho.com/developerconsole.
- Click Add Client ID.
- Enter the client name, domain, and redirect URL.
- Click Create. (Note the Client ID and Client Secret).
User Authorization Request
- Enter this Authorization URL: https://accounts.zoho.com/oauth/v2/auth and along with it pass the parameters as a query string.
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}
Parameters:
- scope - Scope is for a specific module for which the token is to be generated.
- Syntax: ZohoProjects.<module>.<operation>
- Refer the particular API module to know the specific scopes for different operations. Multiple scopes are separated using commas. Eg: ZohoProjects.tasks.READ, ZohoProjects.projects.ALL
- client _id - Client ID is generated while registering the application. This ID uniquely identifies the application that makes the request.
- state - State is returned as a URI parameter.
- response_type - Specify response_type value as code.
- redirect_uri - Specify the redirect URL that you entered during app registration.
- access_type - Allowed values are online or offline.
- Click Accept. You will be redirected back to the "redirect_uri" specified while registering the application. (In case you reject, you will still be redirected back to the redirect_uri).
- You will receive a code parameter on successful authorization. This code is valid only for 2 minutes. Note down the code.
Generate Access and Refresh Token
The code your application received from the authorization endpoint can now be exchanged to get the Access Token and Refresh Token. This code can be exchanged only once.
To Generate tokens:
- Make a POST request to https://accounts.zoho.com/oauth/v2/token and along with it pass the parameters as a query string.
https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code
Parameters:
- grant_type - Specify the value as authorization_code.
- client _id - Specify Client ID obtained while registering the application.
- client_secret - Specify Client Secret obtained while registering the application.
- redirect_uri - Enter the redirect URL that you specified during app registration.
- code - Enter the code generated from previous step (Authorization Request).
- In response, you will receive the following parameters.
| access_token | Access token is used for future requests against the API. |
| expires_in | The number of seconds the access token is valid. Access tokens last only for 3600 seconds (an hour). |
| token_type | Token type is Bearer. |
| refresh_token | Refresh tokens are exchanged to get a new access token. |
The application can make requests of the API using this Access Token for the next hour. Make note of the refresh token which can be used to fetch new Access Tokens when the current one expires.
Regenerate Access Tokens
As long as the user has the application authorized, the Refresh Token can be used to exchange for a new Access Token.
- Make a POST request to https://accounts.zoho.com/oauth/v2/token and along with it pass the parameters as a query string.
https://accounts.zoho.com/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token
- In response, you will receive the following parameters.
| access_token | Access token is used for future requests against the API. |
| expires_in | The number of seconds the access token is valid. Access tokens last only for 3600 seconds (an hour). |
| token_type | Token type is Bearer. |
Revoking Tokens
You can revoke the refresh_token using “POST” method. The following is the URL to revoke the refresh_token.
https://accounts.zoho.com/oauth/v2/token/revoke?token={refresh_token}
Using Access Token in API
You can send the access token in your HTTP authorization header to Zoho Projects API.
- Header Name : Authorization
- Value : Zoho-oauthtoken<space><access_token>
Note:
- The "access_token" is valid only for an hour.