Google Apps Script Add‑ons: Detect Missing OAuth Scopes

Introduction

Google Apps Script add‑ons have always required developers to list every OAuth scope that the script might use. Until recently, users were forced to grant all declared scopes at install time, even if the add‑on would never touch some of them during a particular session. The new “partial permission” model lets users approve only the scopes that are actually needed, improving trust and adoption. However, this flexibility introduces a new challenge: the add‑on must detect when a required scope is missing and guide the user to grant it without breaking the workflow. In this article we will explore the mechanics of partial permissions, show how to programmatically identify missing scopes, and present reliable patterns for prompting users to authorize the exact permissions the add‑on needs.

Understanding Partial Permissions

When an add‑on declares multiple scopes, Google now creates a *granular* consent screen. At runtime the script can operate with a subset of those scopes; any attempt to call a service that requires an undeclared scope triggers a permission error. This model reduces friction but also means that developers can no longer assume all scopes are available. The key concepts to keep in mind are:

• Declared scopes: all scopes listed in the appsscript.json manifest.
• Granted scopes: the subset the user has approved during the current session.
• Scope‑dependent APIs: functions that will fail if the required scope is not granted.

Recognizing this separation helps you design add‑ons that degrade gracefully instead of crashing when a permission is missing.

Detecting Missing OAuth Scopes

The Apps Script runtime provides two main techniques for scope detection:

• Try‑catch blocks around API calls. When a call fails with the error message “You do not have permission to call …”, you can infer that the corresponding scope is missing.
• ScriptApp.getAuthorizationInfo() – this method returns an AuthorizationInfo object that lists requiredScopes and grantedScopes. Comparing the two arrays tells you exactly which permissions are absent.

Example snippet:

var info = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
var missing = info.getRequiredScopes().filter(function(s){ return info.getGrantedScopes().indexOf(s) === -1; });

By centralising this logic in a helper function, you can reuse it across menus, sidebars, and triggers, ensuring consistent detection throughout the add‑on.

Prompting Users for the Required Permissions

Once you know which scopes are missing, you must ask the user to re‑authorize. Google recommends using the built‑in CardService or HTML Service modal dialogs to display a clear, concise message. The flow should be:

1. Explain *why* the additional permission is needed (e.g., “Access to your Drive files is required to attach a PDF”).
2. Provide a button that calls ScriptApp.getAuthorizationUrl() and opens the URL in a new tab.
3. After the user returns, re‑run the original action or refresh the UI.

Sample HTML dialog:

<div>
  <p>We need permission to read your Calendar events.</p>
  <button onclick=”google.script.run.authorize()”>Grant Access</button>
</div>

The authorize() server‑side function simply redirects the user to the URL returned by ScriptApp.getAuthorizationUrl(). This approach keeps the user experience smooth and avoids unexpected script termination.

Best Practices and Edge Cases

To make permission handling robust, follow these guidelines:

• Declare only the scopes you truly need. Over‑declaring forces users to confront unnecessary consent dialogs.
• Group related actions. If several menu items share the same missing scope, request it once and cache the result.
• Handle trigger‑based execution. Installable triggers run with the author’s scopes, not the active user’s. Use AuthMode.LIMITED checks to avoid silent failures.
• Provide a fallback. If a user declines a permission, offer an alternative workflow that does not require that scope, or clearly indicate which features will be unavailable.
• Log missing‑scope events. Recording these incidents helps you prioritize which scopes to request first and improves future UI messaging.

Conclusion

The shift to partial OAuth permissions gives Google Workspace users more control and encourages wider adoption of add‑ons, but it also places responsibility on developers to manage scope availability dynamically. By understanding the distinction between declared and granted scopes, leveraging ScriptApp.getAuthorizationInfo() to detect gaps, and presenting users with clear, contextual prompts, you can create add‑ons that remain functional even when permissions are initially limited. Applying best‑practice patterns—minimal scope declaration, grouped requests, trigger awareness, graceful fallbacks, and thorough logging—ensures a smooth experience that respects user privacy while delivering full functionality. Mastering these techniques will future‑proof your add‑ons and keep them trustworthy in an increasingly security‑focused ecosystem.