Instance-level OAuth with administrator consent
What is an app instance?
An app instance refers to a specific environment or container within a Zoho app. Some Zoho apps support having only one instance (for example, Zoho Mail or Zoho Vault), while others allow multiple instances (for example, Zoho CRM or Zoho Books). The instances may be referred to differently across apps, such as “Organizations” in Zoho CRM and Zoho Books, and “Portals" in Zoho Desk and Zoho Projects.
App instance-level OAuth
When you want to set up an integration that needs access to data across an entire app instance, using the regular user-based OAuth flow can be limiting. Each user must give consent individually, and also their tokens stop working if they revoke access or if a user is removed from the app instance.
With the instance-level OAuth flow, an administrator grants consent once on behalf of the entire instance. The integration can then access the required data from the instance as a whole. And the tokens remain valid even if the administrator who authorized it is later removed from the instance.
An example use case: Your app wants to generate an analytical report using the tickets and agents data pulled from Zoho Desk, specifically from a particular instance (that is, a Portal). With user-based OAuth, each user would have to grant access individually, and the access will be limited to only the tickets associated with them. With instance-level OAuth, the department administrator can grant access once at the Portal level, allowing your app to retrieve the required data.
User-based OAuth | Instance-level OAuth |
|---|---|
Used to access "per-user" resources. | Used to access "instance-wide" resources. |
Consent given by individual users to access their data. | Consent given by an administrator for the data in an instance as a whole. |
Tokens are bound to the user and are invalidated if the user revokes it or if the user is removed from the instance. | Tokens are bound to the app instance and are not invalidated even if the admin who set it up is removed from the instance. It will be invalidated only if the instance gets deleted or it's programmatically revoked. |
Implementing instance-level OAuth
Create a client for the integration
You need to first create an "ORG" type client for each integration. These clients can be created at the API console. Follow the steps below to create an "ORG" client:
Sign in with your Zoho account if prompted.
Enter a name for the client.
Enter the Homepage URL and Authorized Redirect URIs of your app.
INFO:
Homepage URL:
The full URL to your application's home page.Authorized Redirect URI:
It is the URI of the application to which the authorization server (Zoho Accounts) sends the response back to, with the authorization code after the admin grants permission through consent. The URI should begin with https:// or http://. You can add multiple redirect URIs by clicking [plus]. Example: https://www.zylker.com/oauthredirect
Click CREATE. Client ID and Client Secret will be displayed. You can also view them anytime at the API console.
Get consent from admin and generate tokens
Points to note before
Scopes are limited to one Zoho app per refresh token
The client must request for scopes of only one Zoho app per refresh token. This is because in the integration context, a refresh token defines authorization between your client and a single Zoho app, not multiple apps. The exception to this requirement is the scopes of certain common Zoho services listed below:
- ZohoContacts
- ZohoProfile
- ZohoFiles
- AaaServer
User must be an administrator in at least one instance
The user granting permission must be an administrator in at least one instance of the Zoho app mentioned in the scope.
Step 1: Get an authorization code after consent
Request for an authorization code. We will display the requested permissions to the administrator. If they are the administrator of multiple instances, they will have to select which instance to grant permission for. If they grant it, an authorization code will be sent to your redirect URL, which is valid for 2 minutes.
Step 2: Get access token and a refresh token
Exchange the authorization code to receive an access token and a refresh token. Store this refresh token so you can use it to generate new access tokens whenever your apps wants to access the data.
Step 3: Refresh access tokens when needed
Generate new access tokens using your stored refresh token whenever needed. Each access token will be valid for 1 hour.
Revoking tokens
If you want to revoke a refresh token created for an integration, you can make a POST request to oauth/v2/token/revoke. For more details, refer to Revoke OAuth tokens.