Scopes

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.

Note: 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.

Viewing 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 .
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.

Setting 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.

Warning: Always use the least permissive scope set possible. To protect user information, add-ons and other published applications should never ask for more scope permissions then they absolutely need. The scopes your add-on requires are examined during the publication add-on review process; if the add-on uses scopes that are too broad it can't pass review.

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 currently 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.

Note: Avoid using restricted scopes in your add-on if you can—it is easier to pass add-on review for public publication if you don't use them. You can use restricted scopes freely for non-public add-ons.

Choose scopes for Google Workspace Add-ons

The following sections provide scopes that are commonly used for Google Workspace Add-ons.

Editor scopes

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

Scope
Current Docs file access	https://www.googleapis.com/auth/documents.currentonly Required if the add-on accesses the Apps Script Docs API. Grants temporary access to the open document's content.
Current Sheets file access	https://www.googleapis.com/auth/spreadsheets.currentonly Required if the add-on accesses the Apps Script Sheets API. Grants temporary access to the open spreadsheet's content.
Current Slides file access	https://www.googleapis.com/auth/presentations.currentonly Required if the add-on accesses the Apps Script Slides API. Grants temporary access to the open presentation's content.
Per-file access	https://www.googleapis.com/auth/drive.file Required for the add-on to use the onFileScopeGrantedTrigger and if the add-on accesses the Docs, Sheets, Slides, or Drive API. Grants per-file access to files created or opened by the app, using the Apps Script Advanced Drive Service. This doesn't allow the use of similar actions using the basic Drive service, however. File authorization is granted on a per-file basis and is revoked when the user deauthorizes the app.

Gmail

There are a few scopes that were created specifically for Google Workspace Add-ons to help protect user Gmail data. You must add these scopes explicitly to your add-on manifest, along with any others your add-on code requires.

Below are frequently-used scopes for Google Workspace Add-ons that extend Gmail; the ones labeled Required must be added to your Google Workspace Add-on manifest if your add-on extends Gmail.

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

Scope
Create new drafts	https://www.googleapis.com/auth/gmail.addons.current.action.compose Required if the add-on uses compose action triggers. Allows the add-on to temporarily create new drafts messages and replies. See Composing draft messages for details; this scope is also often used with compose actions. Requires an access token.
Read open message metadata	https://www.googleapis.com/auth/gmail.addons.current.message.metadata Grants temporary access to the open message's metadata (such as the subject or recipients). Does not allow reading of message content and requires an access token. Required if the add-on uses metadata in compose action triggers. For compose actions, this scope is required if a compose trigger needs access to metadata. In practice, this scope lets a compose trigger access recipient lists (to:, cc:, and bcc:) of a reply email draft.
Read open message content	https://www.googleapis.com/auth/gmail.addons.current.message.action Grants access to the open message's content upon a user interaction, such as when an add-on menu item is selected. Requires an access token.
Read open thread content	https://www.googleapis.com/auth/gmail.addons.current.message.readonly Grants temporary access to the open message's metadata and content. Also grants access to the content of other messages in the open thread. Requires an access token.
Read any message content and metadata	https://www.googleapis.com/auth/gmail.readonly Read any email metadata and content, including the open message. Required if you need to read information about other messages, such as when conducting a search query or reading an entire mail thread. Warning: This is a very broad, restricted scope. Only use it if absolutely necessary.

Google Calendar scopes

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

Scope
Access event metadata	https://www.googleapis.com/auth/calendar.addons.execute Required if the add-on accesses Calendar event metadata. Allows the add-on to access event metadata.
Read user-generated event data	https://www.googleapis.com/auth/calendar.addons.current.event.read Required if the add-on needs to read user-generated event data. Allows the add-on to access user-generated event data. This data is only available if the addOns.calendar.eventAccess manifest field is set to READ or READ_WRITE.
Write user-generated event data	https://www.googleapis.com/auth/calendar.addons.current.event.write Required if the add-on needs to write user-generated event data. Allows the add-on to edit user-generated event data. This data is only available if the addOns.calendar.eventAccess manifest field is set to WRITE or READ_WRITE.

Google Drive scopes

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

Scope
Read selected item metadata	https://www.googleapis.com/auth/drive.addons.metadata.readonly Required if the add-on implements a contextual interface triggered when the user selects items in Drive. Allows the add-on to read limited metadata about items a user has selected in Google Drive. The metadata is limited to the item's ID, title, MIME type, icon URL and whether the add-on has permission to access the item.
Per-file access	https://www.googleapis.com/auth/drive.file Recommended if the add-on needs to access individual Drive files. Grants per-file access to files created or opened by the app, using the Apps Script Advanced Drive Service. This doesn't allow the use of similar actions using the basic Drive service, however. File authorization is granted on a per-file basis and is revoked when the user deauthorizes the app. See the Request file access for selected files example.

Access tokens

To protect user data, the Gmail scopes used in Google Workspace Add-ons only grant temporary access to user data. To enable temporary access, you must call the function GmailApp.setCurrentMessageAccessToken(accessToken) using an access token as an argument. You must obtain an access token from an action event object.

Note: The access token than enables Gmail scopes is not the same as the access token returned by ScriptApp.getOAuthToken(). You must 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 you can let Apps Script detect these scopes and update the manifest automatically. When editing your manifest's scope list, do not remove any 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:

Scope
Read user's email address	https://www.googleapis.com/auth/userinfo.email Allows the project to read the current user's email address.
Allow calls to external services	https://www.googleapis.com/auth/script.external_request Allows the project to make UrlFetch requests. This is also required if the project makes use of the OAuth2 for Apps Script library.
Read user's locale and timezone	https://www.googleapis.com/auth/script.locale Allows the project to learn the current user's locale and timezone. See Accessing user locale and timezone for details.
Create triggers	https://www.googleapis.com/auth/script.scriptapp Allows the project to create triggers.
Preview third-party links	https://www.googleapis.com/auth/workspace.linkpreview Required if the add-on previews links from a third-party service. Allows the project to see a link within a Google Workspace application while the user is interacting with it. To learn more, see Preview links with smart chips.
Create third-party resources	https://www.googleapis.com/auth/workspace.linkcreate Required if the add-on creates resources in a third-party service. Allows the project to read the information that users submit to the resource creation form and insert a link to the resource within a Google Workspace application. To learn more, see Create third-party resources from the @ menu.