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.
 

Endpoint

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

Note: The accounts-server-url is specific to the location (i.e., datacenter) where your app is registered.

Query parameters

ParameterDescription
client_id

required

The unique ID of your application. You can find this in the API console.

grant_type

required

Should be sent with the value device_request.

scope

required

The corresponding scope for the resource you want to access from the user's account. The scopes will be displayed to the user when asking for consent.

For example: ZohoCRM.settings.READ

access_type

optional

Determines whether your app can refresh the access token on its own once the access token expires (without user intervention). If the 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 app requests for an access token, which the app can store and then use to refresh the access token whenever required. 

Default value: online

prompt

optional

If this parameter is included, the user will be prompted for consent every time your app requests access to the resource. If not included, the user will be prompted only the first time. The value must be consent. 

Request example

Copiedhttps://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_codeA 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_codeA unique code used to identify the device that is requesting for access token. Needs to be passed as a parameter when making the polling request.
intervalThe time duration, in milliseconds, the limited input device needs to wait after a polling request before sending another one.
expires_inThe validity of the device_code in milliseconds.
verification_urlThe 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

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

Error codes

ErrorReasons
invalid_client
  • The accounts-server URL is invalid. Check if the URL is corresponding to your app's datacenter location. See all URLs
  • The parameter client_idis missing or its value is invalid.
400 bad request
  • The parameters may not be spelled correctly.
  • The HTTP method used is invalid. It must be POST.
invalid_response_type
  • The parameter grant_type is missing or its value is invalid.
invalid_scope
  • The parameter scope is missing.
general_error
  • The entered scope doesn't exist.