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

ParameterDescription
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.

ResponseDescription

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.

ResponseDescription

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

ErrorDescription

invalid_client

The client_id parameter is either missing, typed incorrectly, or its value is wrong.
(or)
The account-server URL is not corresponding to the location (i.e., datacenter) where the client is registered.

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_errorUnknown exception. Contact support@zohoaccounts.com.