Polling Request
Get the access token from the Zoho Accounts server by exchanging the device code.
POST {accounts-server-url}/oauth/v3/device/token
Note: The accounts-server-url is specific to the location (i.e., datacenter) where the client is registered. See all the server-specific URLs
Authorization
client_id
query parameter
The unique ID of your application. Obtained from the Zoho API console when you register your application.
client_secret
query parameter
The unique secret of your application which is know only to your application and Zoho Accounts. Obtained from the Zoho API console when you register your application.
Query parameters
Parameter | Description |
grant_type | required Should be passed with the constant value device_token. |
code | required The device_code you have received when you made the initiation request. |
Request example
https://accounts.zoho.com/oauth/v3/device/token
?client_id=1004.JNB00640KVIR87109F4XV941E2SY22
&client_secret=215734b0b2ca5f80f058a4be261e29cbbda609c2b6
&grant_type=device_token
&code=1004.71c4b3d036cbcc5ca5e6f26e4ac0ef11.3a141ff0e7fb15cbf8fc83113b10ec6e
Polling feedback responses
Once a polling request is sent, the Zoho Accounts server will respond with one of the following messages.
Response | Description |
slow_down | Two polling requests have come within 30 seconds. The device must maintain a request rate of only one request per 30 seconds. |
authorization_pending | The user hasn't entered the user_code in the verification_url and granted the requested permissions. |
other_dc | The user granted permission, but the user's datacenter is different from the device's datacenter. The datacenter location of the user will also be included in the response (user_location). Subsequent polling requests from the device have to be sent to this datacenter. See Multi DC |
access_denied | The user has denied permission. |
expired | The user hasn't done any action within the expires_in duration mentioned in the response of the initiation request. |
Polling success response
If the user grants permission, the sever will return the following parameters in the response.
Response | Description |
access_token | An authorized key that can be used by your application to access the protected resource (mentioned in the scope) on behalf of the user. The application can make API requests to the resource using this access token for up to an hour after the creation of the token. |
refresh_token | A special token that can be used by your application to refresh the access token once it is expired. The refresh token will be included in the response if you have passed the parameter access_type with the value offline when making the Initiation request (for the first time). Note: If you want to get a refresh token every time the app requests for an access token, then include the parameters access_type=offline and prompt=consent when making the initiation request. |
api_domain | The domain the app needs to make service API requests to. |
token_type | Indicates the type of access token that is generated and how it must be passed when making API requests to access protected resources. The token type that is used in Zoho OAuth implementation is Bearer. |
expires_in | Indicates the time (in seconds) in which the access token expires. The lifetime of an access token is 1 hour (3600 seconds). |
Response example
{
"access_token": "1004.ce70fccd3edf901d37859fe5124ae975.f61ca1a9d7979387cc02fb3f279",
"refresh_token": "1004.7ed4fdccd7e68a9b898b6ba9538590af.f19b5b44251826323a5c2bae653fe7eb",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}
Possible errors
Error | Description |
invalid_client | The client_id parameter is either missing, typed incorrectly, or its value is wrong. |
invalid_client_secret | The client_secret parameter is either missing, typed incorrectly, or its value is wrong. |
invalid_response_type | The grant_type parameter is either missing or typed incorrectly. |
invalid_scope | The value of the grant_type parameter is entered as device_request. It should be device_token. |
No response/400 bad request | The value of the grant_type parameter is incorrect. It should be device_token. |
invalid_code | The code parameter is either missing, typed incorrectly, or its value is wrong. |
general_error | Unknown exception. Contact support@zohoaccounts.com. |