Authorization 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 the
user's Google Sheets 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, all Gmail
add-ons require the "Add-on Execution" scope, which in your manifest is
written as https://www.googleapis.com/auth/gmail.addons.execute.
During the authorization flow, a script with this scope asks the user to allow
this application to "Run as a Gmail add-on".

Note: The scopes Apps Script uses for its various services overlap with the
scopes uses by the related API. For example, Apps Script's
Calendar service uses the 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:

Open the script project in the Apps Script editor.

In the menu, select File > Project properties.

Select the Scopes tab.

You can also view the script project's current scopes in the project manifest,
under the oauthScopes property, 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, by default Apps Script typically gives Gmail add-on script projects
the very permissive scope https://mail.google.com. 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-on'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 more
more scope permissions then they absolutely need. The scopes your add-on
requires are examined during the publication 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:

Locate the top-level field labeled oauthScopes. If it is not present,
you can add it.

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 Gmail add-on you might have the following:

Editor add-on scopes

When you build an editor add-on, the required scopes are determined by the
Apps Script service and methods the add-on code uses. For example, a Sheets
add-on might need the
https://www.googleapis.com/auth/spreadsheets.readonly scope in order to read
information from different Google Sheets.

Apps Script automatically determines the scopes required by the services you
use as you add code to your script project. For editor add-ons, you can often
just rely on this automatic scope collection instead of determining the scopes
yourself and setting them explicitly.

If you are not setting your scopes explicitly and your editor add-on only ever
reads or writes to the open editor file, add the following comment to one of
your script project files:

/**
* @OnlyCurrentDoc
*/

This comment tells Apps Script to narrow the editor file scopes it sets to
currentonly. For example, if you add this comment to a Sheets add-on script
project file, you are specifying that the add-on only needs permission to
operate on the currently open Sheet, and not any other Sheets the user might
have in Google Drive. Conversely, you shouldn't use this comment if your Sheets
add-on needs to read or write data other Sheets.

Gmail add-on scopes

Unlike editor add-ons, there are a few scopes that were created specifically
for Gmail 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 require.

The following are scopes frequently used in conjunction with Gmail add-ons; the
ones labeled Required must be added to your Gmail add-on manifest.
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.

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.

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 a add-on menu item is selected. Requires an access
token.

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.

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.
This is a very broad Gmail scope and should only be used if
absolutely necessary.

In addition, if your add-on uses other Apps Script services you may need to
include additional scopes. 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.

For reference, here is a list of Apps Script scopes that often are used in
conjunction with Gmail add-ons:

Access tokens

To protect user data, the Gmail add-on scopes only grant temporary access
to user data. To enable this 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 add-on 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.

Restricted scopes

Certain Gmail 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.

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.