Page Summary

outlined_flag

• Add-ons require user authorization and request specific permissions called OAuth scopes to access data or act on a user's behalf.

• Scopes are declared in the add-on's manifest and can be viewed in the script project's overview section, with explicit scope definition recommended for better control and security.

• Certain restricted scopes, particularly for Gmail and Editor add-ons, require careful consideration and adherence to specific guidelines for add-on review and publication.

• Google Workspace add-ons have specific scopes tailored to each service, such as temporary access to document content for Editors, access to message metadata for Gmail, and event access for Calendar, requiring developers to choose the appropriate scope for the desired functionality.

• Using sensitive or restricted scopes might necessitate OAuth client verification, and it is crucial to always use the least permissive scopes possible to minimize security risks and ensure user privacy.

Users must authorize add-ons and other applications that access their dataor act on their behalf. When a user runs an add-on for the first time, theadd-on UI presents an authorization prompt to start the authorization flow.

During this flow, the prompt tells the user what the application wantspermission to do. For example, an add-on might want permission to read auser's email message or create events in their calendar. The add-on's scriptproject defines these individual permissions asOAuth scopes.

You declare scopes in yourmanifestusing URL strings. During the authorization flow, Apps Script presents ahuman-readable description of the scope to the user. For example, your Google Workspace add-onmight use the "Read current message" scope, which is written in your manifest ashttps://www.googleapis.com/auth/gmail.addons.current.message.readonly. Duringthe authorization flow, an add-on with this scope asks the user to allow theadd-on to:View your email messages when the add-on is running.

Viewing 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 under "Project OAuth Scopes."

You can also view the script project's current scopes in the project manifest,under theoauthScopesfield, but only if you have set those scopesexplicitly.

Setting explicit scopes

Apps Script automatically determines what scopes a script needs by scanningits code for function calls that require them. For most scripts this issufficient and saves you time, but for published add-ons you should exercisemore direct control of the scopes.

For example, Apps Script might give an add-on script project the very permissivescopehttps://mail.google.com by default. When a user authorizes a scriptproject with this scope, the project is granted full access to the user's Gmailaccount. For published add-ons, youmust replace this scope with a morelimited set that cover the add-ons's needs and no more.

You can explicitly set the scopes your script project uses by editingitsmanifest file. The manifest fieldoauthScopes is an arrayof all scopes used by the add-on. To set your project's scopes, do thefollowing:

1. View the scopes your add-on currently uses. Determine whatchanges need to be made, such as using a narrower scope.
2. Open your add-on's manifest file.
3. Locate the top-level field labeledoauthScopes. If it is not present,you can add it.

4. TheoauthScopesfield specifies an array of strings. To set the scopesyour project uses, replace the contents of this array with the scopes youwant it to use. For example, for a Google Workspace add-on that extends Gmail you might have the following:

   {  ...  "oauthScopes": [    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",    "https://www.googleapis.com/auth/userinfo.email"  ],  ...}

5. Save the manifest file changes.

OAuth verification

Using certain sensitive OAuth scopes may require that your add-on go throughOAuth client verificationbefore you can publish it. 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

Certain scopes arerestricted and subject to additional rules that helpprotect user data. If you intend to publish a Gmail or Editor add-on that usesone or more restricted scopes, the add-on must comply with all the specifiedrestrictions before it can be published.

Review thefull list of restricted scopesbefore you attempt to publish. If your add-on uses any of them, you must complywith theAdditional requirements for specific API scopesprior to publishing.

TheGoogle Workspace Developer Tools extension for Visual Studio Code provides diagnostic information for all scopes including the scope's description and whether it is sensitive or restricted.

Choose scopes for Google Workspace add-ons

The following sections provide scopes that are commonly used forGoogle Workspace add-ons.

Editor scopes

Below are frequently-used scopes for Google Workspace add-ons that extend Docs, Sheets,and Slides.

Gmail

There are a few scopes that were created specifically forGoogle Workspace add-ons to help protect user Gmaildata. You mustadd these scopes explicitlyto your add-on manifest, along with any others youradd-on code requires.

Below are frequently-used scopes for Google Workspace add-ons that extend Gmail;the ones labeledRequired must be added to yourGoogle Workspace add-on manifest if your add-on extendsGmail.

Be sure to also replace the very broadhttps://mail.google.com scope in youradd-on with a narrower set of scopes that allow the interactions your add-onneeds and no more.

Google Calendar scopes

Below are frequently-used scopes for Google Workspace add-ons that extend Google Calendar.

Google Chat scopes

To call the Chat API, you must authenticate as theGoogle Chat user or as theChat app.Each type of authentication requires different scopes, and not allChat API methods support app authentication.

To learn more about Chat scopes and authentication types, see theChat APIAuthentication and authorization overview

The following table shows frequently-used Chat API methods and scopesbased on the supported authentication types:

Google Drive scopes

Below are frequently-used scopes for Google Workspace add-ons that extend Google Drive.

Access tokens

To protect user data, the Gmail scopes used inGoogle Workspace add-ons only granttemporary access to user data. To enable temporary access, you must call thefunctionGmailApp.setCurrentMessageAccessToken(accessToken)using an access token as an argument. You must obtain an access token from anaction event object.

The following shows an example of setting an access token to allow access toa message's metadata. The only scope necessary for this example ishttps://www.googleapis.com/auth/gmail.addons.current.message.metadata.

functionreadSender(e){varaccessToken=e.gmail.accessToken;varmessageId=e.gmail.messageId;//Thefollowingfunctionenablesshort-livedaccesstothecurrent//messageinGmail.AccesstootherGmailmessagesordataisn't//permitted.GmailApp.setCurrentMessageAccessToken(accessToken);varmailMessage=GmailApp.getMessageById(messageId);returnmailMessage.getFrom();}

Other Google Workspace scopes

Your add-on may require additional scopes if it uses other Google Workspace or Apps Script services.In most cases you can let Apps Script detect these scopes and update themanifest automatically. When editing your manifest's scope list, do not removeany scopes unless you are replacing them with a more appropriate alternative,such as a narrower scope.

The following table shows a list of scopes that Google Workspace add-ons often use: