OAuth 2.0 Token
Zoho Apptics 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. Each API request must include an OAuthToken to retrieve any resource from Zoho Apptics portal. Ensure that you have permission to access the API service. If not, please contact support@zohoapptics.com.
Obtaining the OAuthToken
Register your app in Zoho developer console.
- Navigate to the Zoho developer console.
- In the API credentials page, click on add client ID to create a new client ID and client secret.
- 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.)
- You will get a set of OAuth 2.0 details with the client ID and client secret shared only between Zoho and the application.
Request URL
https://accounts.zoho.com/oauth/v2/auth
Obtain the Authorization Grant
Obtain an authorization grant by invoking the authorization URL, that contains the parameters listed in the table below.
Parameter | Description |
---|---|
client_id | client ID is generated after registering the client. |
response_type | "code" |
redirect_url | redirect URL mentioned while registering the client. |
scope | various scopes associated with Zoho Apptics. |
access_type | "offline/online". In cases where refresh tokens can't be stored, use online access_type. The default will be online. |
state | an opaque value used by the client to maintain state between request and callback. |
After you invoke the authorization URL, a "user-consent" page opens. Once the user accepts, a GET request will be made to the redirect_uri with the authorization code appended in the query param.
Obtain the access token
Invoke a URL in the following format to exchange the authorization code (that you got in the previous step) with an OAuth Token.
Parameter | Description |
---|---|
code | authorization code obtained after generating the grant token |
client_id | client ID is obtained after registering the client |
client_secret | client secret is obtained after registering the client |
scope | specify the scope allowed for Zoho Apptics |
grant_type | "authorization_code" |
redirect_url | redirect URL is mentioned while registering the client |
state | state is an opaque value used by the client to maintain state between the request and callback. Has to be maintained the same during the entire process for authenticity |
After invoking the URL, you will be presented with an access token, which you must include in all API calls.
Generating access token from a refresh token
Access tokens generally expire in one hour. You will have to generate a new access token to keep the process going. You can eliminate the need to perform the entire procedure to generate access tokens, by using refresh tokens. Once the access token expires, the refresh token can be obtained only when access_type is set to offline while creating the access token.
Using OAuth in API calls
To invoke Zoho Apptics APIs, pass the access token in the authorization parameter in the header, as shown in the example.
OAuth Scopes
The various scopes accessible using Zoho Apptics APIs are as follows:
- Scope: A scope determines which protected resource of an end-user a client has requested access to. A scope contains three parameters: service name, scope name, and operation type.
- Service name: All Zoho products have a service name, such as Apptics.
- Scope name: Each product has user data divided into groups defined by scope names.
- Operation type: This can be ALL, READ, CREATE, DELETE, or UPDATE.
- Syntax: Service_name.scope_name.OPERATION
- Example: JProxy.jmobileapi.ALL
- You can request an access token with multiple scopes.
Query params
Copied?code=1000.fadbca4c2be2f08b0ce82a54f4313.ba5325853af6f12a0f160
&grant_type=authorization_code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&redirect_uri=https://apptics.zoho.com/token
&scope=JProxy.jmobileapi.ALL
Response example
Copied{
"access_token": "1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6",
"refresh_token": "1000.aed4288cd9cfb2d63d093faef1b98890.2f4aa58ddadbec9fbbfd683805da839b",
"expires_in_sec": 3600,
"token_type": "Bearer",
"expires_in": 3600000
}
Access token URL
CopiedResponse Example
{
"access_token": "1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6",
"refresh_token": "1000.aed4288cd9cfb2d63d093faef1b98890.2f4aa58ddadbec9fbbfd683805da839b",
"expires_in_sec": 3600,
"token_type": "Bearer",
"expires_in": 3600000
}
Generating Access Token from a Refresh Token
CopiedPOST - https://accounts.zoho.com/oauth/v2/token
Query Params
?refresh_token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&scope=JProxy.jmobileapi.ALL
&redirect_uri=https://apptics.zoho.com/token
&grant_type=refresh_token
Generating Access Token from a Refresh Token
Copied{
"access_token": "1000.2d4437b4f862641d76dedac5f95a3f8a.fac6eb7129da540de1d53b06562e744d",
"expires_in_sec": 3600,
"token_type": "Bearer",
"expires_in": 3600000
}
Generating Access Token from a Refresh Token
Copied{
"phone": "1 888 900 9646",
"assigneeId": "1892000000056007",
"subject": "Welcome to Zoho Desk. You've got a sample Request!",
"timeEntryCount": "3",
"resolution": null,
"id": "1892000000042034",
"closedTime": null,
"webUrl": "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38",
"description": "Hello! Welcome to Zoho Desk.
I am glad to assist you deliver more happiness in every support request.Thank you for choosing Zoho Desk,
Lawrence
Customer Support Executive",
"priority": "High",
"customerResponseTime": "2017-11-04T11:21:07.912Z",
"approvalCount": "1",
"dueDate": "2017-11-05T16:16:16.000Z",
"customFields": {
"location": "Asia"
},
"createdTime": "2017-11-04T11:21:07.000Z",
"status": "Open",
"modifiedTime": "2017-11-04T13:16:14.000Z",
"ticketNumber": "101",
"commentCount": "1",
"attachmentCount": "1",
"productId": null,
"category": "Customer Request",
"contactId": "1892000000042032",
"email": "steve@zylker.com",
"taskCount": "1",
"subCategory": "Feature Request",
"classification": null,
"threadCount": "121",
"departmentId": "1892000000006907",
"channel": "Email"
}