Image credit: Dave Abouav

A collection of helpful functions for Apps Script powered scripts, Add-ons and Chat Apps for checking if all of a script’s OAuth scopes (as listed in the project’s manifest file) have been authorized/granted by the end-user, and if not, then to prompt the user to re-authorize.

As we’ve covered previously, Google continues to roll out granular OAuth consent for published Editor Add-ons. This change gives users more control but requires developers to adapt their code to prevent a broken experience for new users.

While Google has provided new Apps Script methods for developers, distinguished Google Workspace Developer Dave Abouav has gone a step further by creating a simple, drop-in solution to help developers address this change quickly.

The Challenge: Handling Partial Permissions

With the new consent screen, users can grant only a subset of the OAuth scopes your add-on requests. If a new user deselects a scope that is essential for a particular feature, your add-on could fail, leaving the user without a clear path forward.

A Simple, Ready-Made Solution

Dave’s solution addresses this by providing a function that checks for incomplete authorization. When the function is triggered and finds that necessary permissions are missing, it automatically displays a user-friendly dialog. This prompt explains the situation and provides a direct link for the user to grant the required access.

The implementation is straightforward. After adding the granularAuth.gs file to your project, you’ll need to configure two constants at the top of the file:

1. Set AUTH_APP_NAME to your add-on’s name to ensure the re-authorization prompt is correctly branded.
2. Crucially, update the ADD_ON_CONTAINERS array to list only the host applications your add-on is designed for. This prevents your add-on from requesting unnecessary permissions (e.g., asking for Google Docs access when it’s a Sheets-only add-on).

// Set your Add-on's name here.
const AUTH_APP_NAME = 'My Awesome Add-on';

// To avoid requesting unnecessary scopes, list ONLY the hosts this add-on is for.
// For a Sheets-only add-on, for example, you would use:
const ADD_ON_CONTAINERS = [SpreadsheetApp];

Once configured, you can call the main function at the entry points of your add-on, such as from a menu item:

function menuItemStartAction() {
  if (authHandleMissingScopeGrants()) {
    // The prompt has been shown, so abort normal execution.
    return;
  }

 // Continue with normal execution
 handleStartAction();
}

This simple check ensures your add-on has the permissions it needs to run, and if not, it provides the user with an immediate path to resolution. Crucially, deploying this update doesn’t trigger the need for a new review from the OAuth or Marketplace teams.

It’s worth noting that this solution is specifically designed for Editor Add-ons (Forms, Sheets, Docs, and Slides). Adapting it for Workspace Add-ons would require modifications to use the Card Service for the user interface.

A big thank you to Dave Abouav for creating and sharing this valuable resource with the community! You can find the complete code, setup instructions, and more details on his GitHub repository.

Source: Dave Abouav’s granularOAuth GitHub Repository