Initiation request

Get the device code, user code, and verification url from the Zoho Accounts server, which are needed to get the permission from the user and to make the polling request.

POST         {accounts-server-url}/oauth/v3/device/code

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.
 

Query parameters

ParameterDescription
grant_type

required

Should be passed with the constant value device_request.

scope

required  

The corresponding scope for the resource you want to access using the access token. To add multiple scopes, separate them using commas. The scopes will be displayed to the user when asking for consent.
Eg:ZohoCRM.settings.READ

access_type                

optional

Determines whether the application can refresh the access token on its own once the access token expires. If value is online, only the access token will be provided and it cannot be refreshed by the app once expired. If the value is offline, a refresh token will also be provided for the first time the application requests for an access token, which the app can store and then use to refresh the access token whenever required.

Default value: online

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 authorization request.

prompt

optional

specifies whether consent should be asked from the user every time the app requests for access. If you don't include this parameter, consent will be asked only the first time the app requests for access. To make the app always ask for consent, use the value consent.

Default value: none


Request example

https://accounts.zoho.com/oauth/v3/device/code
?grant_type=device_request
&client_id=1000.GMB0YULZHJK411284S8I5GZ4CHUEX0
&scope=AaaServer.profile.Read
&access_type=offline
&prompt=consent


Response parameters

ParameterDescription
user_code

A unique code that user should enter in a browser to grant permission to the client. This code needs to be displayed to the user.

Validity: 5 minutes

device_code             

A unique code used to identify the limited input device that is requesting for access token. Needs to be passed as a parameter when making the polling request.

interval              

The time duration, in milliseconds, the limited input device needs to wait after a polling request before sending another one.

expires_in

The validity of the device code.

verification_url

The URL the user must navigate to in a browser in order to grant permission to the requesting client. The user would need to go to this URL and then enter the user_code. This URL needs to be displayed to the user.


Response example

{
"user_code":"ABCD-1234",
"device_code":"1004.c458057b370ec928086e679db8fbf15d.2dbe3e41e18b39e33236fb72ff3b1fd4","interval":30000,
"expires_in":300000,
"verification_url":"https://accounts.zoho.com/oauth/v3/device"
}


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_response_type    

The grant_type parameter is either missing or typed incorrectly.

invalid_scope              

The scope parameter is either missing or typed incorrectly, or the entered scope value doesn't exist.

No response / 400 bad request    The value of the grant_type parameter is incorrect. It should be device_request.
general_error

Unknown exception. Contact support@zohoaccounts.com.