Users must authorize script projects that access their data or act on their
behalf. When a user runs a script that requires authorization for the first
time, the UI presents a prompt to start the authorization flow.
During this flow, the UI tells the user what the script wants permission
to do. For example, a script might want permission to read the user's
email messages or create events in their calendar. The script project
defines these individual permissions as
OAuth scopes
.
For most scripts, Apps Script automatically detects what scopes
are needed for you; you can
view the scopes
a script uses
at any time. You can also
set scopes explicitly
in your
manifest
using URL strings. Setting
scopes explicitly is sometimes required for certain applications like
add-ons
, since published applications should
always use the narrowest scopes possible.
During the authorization flow, Apps Script presents human-readable
descriptions of the required scopes to the user. For example, if your script
needs read-only access to your spreadsheets, the manifest may have the scope
https://www.googleapis.com/auth/spreadsheets.readonly
. During the
authorization flow, a script with this scope asks the user to allow this
application to "View your Google Spreadsheets".
Some scopes are inclusive of others. For example, when authorized the scope
https://www.googleapis.com/auth/spreadsheets
allows read and write access to
spreadsheets.
Viewing scopes
You can see the scopes your script project currently requires by doing the
following:
- Open the script project.
- At the left, click
Overview
info_outline
.
- View the scopes under
Project OAuth Scopes
.
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, web
apps, Google Chat apps, and calls to Google Chat API you must exercise more
direct 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 bad
practice. For published scripts, you must replace broad scopes with a
more limited set that cover the script'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 project. To set your
project's scopes, do the following:
- Open the script project.
- At the left, click
Project Settings
settings
.
- Select the
Show "appsscript.json" manifest file in editor
checkbox.
- At the left, click
Editor
code
.
- At the left, click the
appsscript.json
file.
- Locate the top-level field labeled
oauthScopes
. If it's 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:
{
...
"oauthScopes": [
"https://www.googleapis.com/auth/spreadsheets.readonly",
"https://www.googleapis.com/auth/userinfo.email"
],
...
}
- At the top, click Save
save
.
OAuth verification
Certain OAuth scopes are
sensitive
because they allow access to Google
User Data. If your script project uses scopes that allow access to user data,
the project must go through
OAuth client verification
before you can publish it publicly as a web app or
add-on
.
For more information, see the following guides:
Restricted scopes
In addition to sensitive scopes, certain scopes are classified as
restricted
and subject to additional rules that help protect user data. If you intend to
publish a web app or
add-on
that uses one or more
restricted scopes, the app 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 app uses any of them, you must comply
with the
Additional Requirements for Specific API scopes
prior to publishing.