Scopes

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 data or act on their behalf. When a user runs an add-on for the first time, the add-on UI presents an authorization prompt to start the authorization flow.

During this flow, the prompt tells the user what the application wants permission to do. For example, an add-on might want permission to read a user's email message or create events in their calendar. The add-on's script project defines these individual permissions as OAuth scopes.

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

The scopes Apps Script uses for its various services overlap with the scopes used by the related API. For example, Apps Script's Calendar service uses many of the same scopes as the Calendar API. You can look up the scopes that particular Apps Script service methods require in the Apps Script reference documentation.

View scopes

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

1. Open the script project.
2. At the left, click Overview info_outline.
3. View the scopes under "Project OAuth Scopes."

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

Set explicit scopes

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

For example, Apps Script might give an add-on script project the very permissive scope https://mail.google.com by default. When a user authorizes a script project with this scope, the project is granted full access to the user's Gmail account. For published add-ons, you must replace this scope with a more limited set that cover the add-ons's needs and no more.

You can explicitly set the scopes your script project uses by editing its manifest file. The manifest field oauthScopes is an array of all scopes used by the add-on. To set your project's scopes, do the following:

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

4. The oauthScopes 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, 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 through OAuth client verification before 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 are restricted and subject to additional rules that help protect user data. If you intend to publish a Gmail or Editor add-on that uses one or more restricted scopes, the add-on must comply with all the specified restrictions before it can be published.

Review the full list of restricted scopes before you attempt to publish. If your add-on uses any of them, you must comply with the Additional requirements for specific API scopes prior to publishing.

The Google 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 for Google Workspace add-ons.

Editor scopes

The following frequently-used scopes for Google Workspace add-ons extend Google Docs, Google Sheets, and Google Slides.

Gmail

There are scopes created specifically for Google Workspace add-ons to help protect user Gmail data. Add these scopes explicitly to your add-on manifest, along with any others required.

The following table lists frequently-used scopes for Google Workspace add-ons that extend Gmail. If your add-on extends Gmail, you must add any scopes labeled Required to your Google Workspace add-on manifest.

Replace the broad https://mail.google.com scope with a narrower set of scopes that allow the interactions your add-on needs.

Google Calendar scopes

The following table lists frequently-used scopes for Google Workspace add-ons that extend Google Calendar.

Google Chat scopes

To call the Google Chat API, authenticate as the Google Chat user or as the Google Chat app. Each type of authentication requires different scopes, and not all Chat API methods support app authentication.

To learn more about Chat scopes and authentication types, see the Chat API Authentication and authorization overview

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

Google Drive scopes

The following table lists frequently-used scopes for Google Workspace add-ons that extend Google Drive.

Access tokens

To protect user data, the Gmail scopes used in Google Workspace add-ons grant temporary access to user data. To enable temporary access, call GmailApp.setCurrentMessageAccessToken using an access token from an action event object.

The access token that enables Gmail scopes isn't the same as the access token returned by ScriptApp.getOAuthToken. Use the token provided in the action event object.

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

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.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, Apps Script detects these scopes and updates the manifest automatically. When editing your manifest's scope list, don't remove any scopes unless you are replacing them with a narrower alternative.

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