What are non-browser apps
Some apps run on devices that don't have a browser and only have limited input capabilities, such as TVs and printers. Hence, users won't be able to grant permission to the app directly, the regular OAuth flow can't be used. These apps are called Non-browser apps.
For such apps, the "Device Authorization Grant" flow has to be used. To request for permission, the app will need to display a URL and verification code to the user. The user will have to go to the verification URL (in a browser of their mobile device or computer) and enter the code to grant permission. After the permission is granted, an access token and refresh token will be provided to the app.
Device authorization grant flow
Step 1: Client registration
Register your client with the Zoho API console and generate client ID and client secret.
Step 2: Initiation request
The device won't be able to get permission from the user directly, due to the lack of a browser. The device needs to make an initiation request to Zoho Accounts server to get the following:
- user_code - this will be used to get permission from the user
- verification_url - this is the URL that the user should access from a browser, and enter the user code in.
- device_code - this will be used to get the access token (during polling request).
See API reference for initiation request
Step 3: Display the user code and verification URL to user
After the initiation request, the device must display the verification_URL and user_code to the user. The user can grant permission to the device by navigating to the verification_URL from their mobile phone or laptop and entering the user_code. Simultaneously, the device will have to send polling requests to the Zoho server.
When the user navigates to the verification_URL in a browser, the following screen will be shown, where the user needs to enter the user_code and click Verify. After clicking Verify, the required permissions will be shown. The user needs to grant permission by clicking Accept.
Step 4: Polling request
If the user has granted permission, the device can make requests to the Zoho server to get an access token. But the device won't know whether the user has granted permission or not. Hence, the device will have to keep polling requests to the server at a rate of 1 request per 30 seconds. The server will respond with a feedback response depending on the user's action. If the user has granted permission, the server will provide the access token to the device.
Step 5: Access resources
Using the access token, the device can access the resources specified in the scope.
Multi DC support
In Zoho, we use different data centers (DC) to store users' information. This information is not shared between data centers. Learn more about data centers
If your app is registered in the a certain DC, to access the data of the users in other DCs, then you need to enable multi DC support for your app. After you enable this support, when you make API calls, you will have to change your endpoint URL depending on the user's DC.
Revoking refresh tokens
Refresh tokens can be revoked programmatically or by the user themselves.
Refresh tokens can be revoked by users in two ways:
- Users can go to the Connected Apps section in accounts.zoho.com and revoke the access they've granted for an app.
- Users can choose to revoke access for connected apps when they change their password, or enable multi-factor authentication (MFA).
Programmatically, refresh tokens can be revoked by making a POST request to the endpoint oauth/v2/token/revoke. Refer API reference
Note: Access tokens can also be revoked programmatically. When an access token is revoked, if it is granted via a refresh token, it will also get revoked.