Page Summary

outlined_flag

• Script projects accessing user data require authorization, initiating an authorization flow when a script runs for the first time.

• OAuth scopes define the specific permissions a script needs, such as reading emails or creating calendar events.

• For most scripts, Apps Script automatically detects necessary scopes, but for published applications like add-ons, you should explicitly set the narrowest scopes possible in the manifest file.

• Granular OAuth permissions allow users to authorize specific scopes, and scripts should be designed to handle these permissions usingrequireScopes orgetAuthorizationInfo methods.

• Scripts using sensitive or restricted OAuth scopes, especially for publicly published applications, may require OAuth client verification and adherence to additional data policies.

Users must authorize script projects that access their data or act on theirbehalf. When a user runs a script that requires authorization for the firsttime, the UI presents a prompt to start the authorization flow.

During this flow, the UI tells the user what the script wants permissionto do. For example, a script might want permission to read the user'semail messages or create events in their calendar. The script projectdefines these individual permissions asOAuth scopes.

For most scripts, Apps Script automatically detects what scopesare needed for you; you canview the scopes a script usesat any time. You can alsoset scopes explicitlyin yourmanifest using URL strings. Settingscopes explicitly is sometimes required for certain applications likeadd-ons, since published applications shouldalways use the narrowest scopes possible.

During the authorization flow, Apps Script presents human-readabledescriptions of the required scopes to the user. For example, if your scriptneeds read-only access to your spreadsheets, the manifest may have the scopehttps://www.googleapis.com/auth/spreadsheets.readonly. During theauthorization flow, a script with this scope asks the user to allow thisapplication to "View your Google Spreadsheets".

Some scopes are inclusive of others. For example, when authorized the scopehttps://www.googleapis.com/auth/spreadsheets allows read and write access tospreadsheets.

For some surfaces where scripts run, such as running a scriptdirectly from the Apps Script IDE, users are presented with thegranular OAuth consent screen. This lets users select specific permissions togrant rather than granting all permissions at once. It's important to designyour script tohandle granular OAuth permissions.

View scopes

You can see the scopes your script project currently requires by doing thefollowing:

1. Open the script project.
2. At the left, clickOverviewinfo_outline.
3. View the scopes underProject OAuth Scopes.

Set explicit scopes

Apps Script automatically determines what scopes a script needsby scanning its code for function calls that require them. For most scripts thisis sufficient and saves you time, but for published add-ons, webapps, Google Chat apps, and calls to Google Chat API you must exercise moredirect control of the scopes.

Apps Script sometimes automatically assigns projects very permissive scopes.This can mean your script asks the user for more than it needs, which is badpractice. For published scripts, you must replace broad scopes with amore limited set that cover the script's needs and no more.

You can explicitly set the scopes your script project uses by editingitsmanifest file. The manifest fieldoauthScopes is an array of all scopes used by the project. To set yourproject's scopes, do the following:

1. Open the script project.
2. At the left, clickProject Settingssettings.
3. Select theShow "appsscript.json" manifest file in editor checkbox.
4. At the left, clickEditorcode.
5. At the left, click theappsscript.json file.
6. Locate the top-level field labeledoauthScopes. If it's not present, you can add it.
7. TheoauthScopes field specifies an array of strings. To set the scopes your project uses, replace the contents of this array with the scopes you want it to use. For example:

         {        ...        "oauthScopes": [          "https://www.googleapis.com/auth/spreadsheets.readonly",          "https://www.googleapis.com/auth/userinfo.email"        ],       ...      }

8. At the top, click Savesave.

Handle granular OAuth permissions

The granular OAuth consent screen lets users specify which individual OAuthscopes they want to authorize. Granular OAuth permissions give users morefine-grained control over what account data they choose to share with eachscript. For example, imagine you develop a script that requests permission forboth email and calendar scopes. Your users mightwant to use your script only for its capabilities with Google Calendar, butnot Gmail. With granular OAuth permissions, users can choose to onlygrant Calendar permission, but not Gmail.

The following sections describe the main ways to handle granular OAuthpermissions.

Automatically require permission for necessary scopes

If an execution flow needs permission for scopes in order to work,you can require users to grant those permissions before they can use it.Your script can check if the user has already given permission and, if not,automatically ask them for it.

The following methods from theScriptApp class let you validatepermission for required scopes and automatically renderthe authorization prompt to request any missing permissions:

• requireScopes(authMode, oAuthScopes):Use this method for execution flows that rely on one or more scopes, but not allthe scopes used by your script.
• requireAllScopes(authMode):Use this method if an execution flow relies on all of the scopes used by yourscript.

Example

The following example shows how to call therequireScopes(authMode, oAuthScopes) andrequireAllScopes(authMode) methods.The script uses scopes for Gmail, Sheets, andCalendar.ThesendEmail() function requires only the scopes for Gmail andSheetswhile thecreateEventSendEmail() function requires all scopes used by thescript.

// This function requires the Gmail and Sheets scopes.functionsendEmail(){// Validates that the user has granted permission for the Gmail and Sheets scopes.// If not, the execution ends and prompts the user for authorization.ScriptApp.requireScopes(ScriptApp.AuthMode.FULL,['https://mail.google.com/','https://www.googleapis.com/auth/spreadsheets']);// Sends an email.GmailApp.sendEmail("dana@example.com","Subject","Body");Logger.log("Email sent successfully!");// Opens a spreadsheet and sheet to track the sent email.constss=SpreadsheetApp.openById("abc1234567");constsheet=ss.getSheetByName("Email Tracker")// Gets the last row of the sheet.constlastRow=sheet.getLastRow();// Adds "Sent" to column E of the last row of the spreadsheet.sheet.getRange(lastRow,5).setValue("Sent");Logger.log("Sheet updated successfully!");}// This function requires all scopes used by the script (Gmail,// Calendar, and Sheets).functioncreateEventSendEmail(){// Validates that the user has granted permission for all scopes used by the// script. If not, the execution ends and prompts the user for authorization.ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);// Creates an event.CalendarApp.getDefaultCalendar().createEvent("Meeting",newDate("November 28, 2024 10:00:00"),newDate("November 28, 2024 11:00:00"));Logger.log("Calendar event created successfully!");// Sends an email.GmailApp.sendEmail("dana@example.com","Subject 2","Body 2");Logger.log("Email sent successfully!");// Opens a spreadsheet and sheet to track the created meeting and sent email.constss=SpreadsheetApp.openById("abc1234567");constsheet=ss.getSheetByName("Email and Meeting Tracker")// Gets the last rowconstlastRow=sheet.getLastRow();// Adds "Sent" to column E of the last rowsheet.getRange(lastRow,5).setValue("Sent");// Adds "Meeting created" to column F of the last rowsheet.getRange(lastRow,6).setValue("Meeting created");Logger.log("Sheet updated successfully!");}

Create a custom experience for missing scopes

You can get the permission details of the user running your script and designa custom experience based on their permission status. For example, you mightdecide to turn off specific features of your script that require permissionsthat the user hasn't granted, or present a custom dialog explaining the missingpermissions. The following methods get an object with theuser's permission information that includes which scopes the user hasauthorized and a URL to let you request any missing scopes:

• getAuthorizationInfo(authMode, oAuthScopes):Use this method to check the permission status for specific scopes.
• getAuthorizationInfo(authMode):Use this method to check the permission status for all scopes used by yourscript.

To get the permission details from the authorization info object, such as a listof which scopes have been authorized and a URL to request missing permissions,use the methods from theAuthorizationInfo class.

Example

The following example shows how to call thegetAuthorizationInfo(authMode, oAuthScopes) method to skip specific featureswithin an execution flow where the required scopes haven't been granted. Thislets the rest of the execution flow continue without having to prompt forauthorization of the missing scopes.

// This function uses the Gmail scope and skips the email// capabilities if the scope for Gmail hasn't been granted.functionmyFunction(){constauthInfo=ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL,['https://mail.google.com/']);if(authInfo.getAuthorizationStatus()===ScriptApp.AuthorizationStatus.NOT_REQUIRED){GmailApp.sendEmail("dana@example.com","Subject","Body");Logger.log("Email sent successfully!");}else{constscopesGranted=ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();console.warn(`Authorized scopes:${scopesGranted} not enough to send mail, skipping.`);}// Continue the rest of the execution flow...}

Ensure that trigger executions have permissions

Functions associated with triggers can run automatically on certain events, andthe user may not be present to provide more permissions. Werecommended that you userequireScopes(authMode, oAuthScopes)before installing a trigger. This prompts the user for missing permissionsand doesn't allow the installation of the trigger without them.

Example

// This function requires scope Sheets.functiontrackFormSubmissions(e){// Opens a spreadsheet to track the sent email.constss=SpreadsheetApp.openById("abc1234567");constsheet=ss.getSheetByName("Submission Tracker")// Gets the last row of the sheet.constlastRow=sheet.getLastRow();// Adds email address of user that submitted the form// to column E of the last row of the spreadsheet.sheet.getRange(lastRow,5).setValue(e.name);Logger.log("Sheet updated successfully!");}functioninstallTrigger(){// Validates that the user has granted permissions for trigger// installation and execution. If not, trigger doesn't get// installed and prompts the user for authorization.ScriptApp.requireScopes(ScriptApp.AuthMode.FULL,['https://www.googleapis.com/auth/script.scriptapp','https://www.googleapis.com/auth/spreadsheets','https://www.googleapis.com/auth/forms.currentonly']);ScriptApp.newTrigger('trackFormSubmission').forForm(FormApp.getActiveForm()).onFormSubmit().create();}

OAuth verification

Certain OAuth scopes aresensitive because they allow access to GoogleUser Data. If your script project uses scopes that allow access to user data,the project must go throughOAuth client verificationbefore you can publish it publicly as a web app oradd-on.For more information, see the following guides:

• OAuth client verification for Apps Script
• Unverified apps
• OAuth verification FAQ
• Google APIs Service: User Data Policy

Restricted scopes

In addition to sensitive scopes, certain scopes are classified asrestrictedand subject to additional rules that help protect user data. If you intend topublish a web app oradd-on that uses one or morerestricted scopes, the app must comply with all the specified restrictionsbefore it can be published.

Review thefull list of restricted scopesbefore you attempt to publish. If your app uses any of them, you must complywith theAdditional Requirements for Specific API scopes prior to publishing.