Server-based apps - Overview
What are server-based apps
Server-based apps typically involve a separation between the front-end (client-side) and back-end (server-side) components. The application logic is performed on the server, and the rendered content is sent to the browser for display.
These apps can securely store credentials on the server-side, such as client secrets, and are referred to as "confidential clients" in OAuth terminology.
For such apps, the Authorization Code Flow is used to obtain access tokens. It involves exchanging an authorization code (received from the authorization server) for access tokens. Refresh tokens can also be obtained in this flow, allowing the server-based app to obtain new access tokens without requiring user intervention.
Authorization code flow
To begin with, you need to register your app in the API console as a "server-based app". You will get a client ID and client secret. You will need them to make the API calls to receive OAuth tokens. Once you receive an access token, you can use it to access the protected resources of Zoho.
The authorization code flow to obtain access token is as follows:
Step 1:
Make a GET request to the endpoint oauth/v2/auth mentioning the required scopes. The end user will be displayed the permissions you're requesting. If the user grants access, an authorization code will be returned to the redirection URL. This code will be valid for 2 minutes.
Step 2:
Using the received authorization code, make a POST request to the endpoint oauth/v2/token. The authorization server will return an access token and an optional refresh token. This access token will be valid for 1 hour.
Step 3:
Using the received access token, you can call the Zoho APIs to access protected resources. If you need to access the resources again after the access token expires, you can use the refresh token to obtain access tokens whenever required. Send a POST request to the endpoint oauth/v2/token with the refresh token to obtain another access token.
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.
Incremental authorization
Incremental authorization allows your app to request for a permission from the user only when it is needed and not upfront. Let's say your app needs to obtain profile information of the user to provide basic functionality; and for certain features, need additional permission. Normally, your app will have to request profile info permission and additional permissions upfront when user grants access. But this would provide a bad experience for the user because they would have to give permission for features which they aren't even using yet. Incremental authorization helps avoid this and provides a better user experience.
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.