Incremental authorization - Overview

Incremental authorization is an OAuth implementation strategy that allows your app to get a required permission from the user only when it is needed and not upfront. It improves the user experience of your app.

It has the following advantages:

• Your users won’t have to grant permission to the scopes that they don’t have to (i.e., for features that they’re not going to use).
• Your app doesn’t have to repeatedly ask for permissions that are already granted by the user.

For example, let’s say you’re developing an app that integrates with Zoho Mail. When the user signs in, your app only needs to get the user’s basic profile information and also the permission to display the user’s inbox and emails in your app. Later, user may choose to send emails right from your app (which your app supports). Now, your app can request permission from the user to send emails. At this time, the user will be asked only the permission to send emails and not the already granted permissions such as basic profile information and view emails permission.

How it works

Initially, your app would have got the basic permissions that are needed upfront. Later on, when your app needs to ask for further permissions from the user, follow these steps.

1. Get a scope enhancement token from Zoho by making a POST request to the oauth/v2/token/scopeenhance endpoint. You will also need to send a refresh token as a parameter. See API reference
2. Make a scope enhancement request to the oauth/v2/token/addextrascope endpoint with the scope enhancement token. You will need to include what additional scopes are needed. See API reference

User will be prompted with the consent screen asking for the newly required permissions. If the user approves, the refresh token (sent in step 1) and its associated access tokens will be appended with the additional scopes, and a success response will be returned.