Authorization Scopes

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:

  1. Open the script project.
  2. At the left, click Overview .
  3. 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:

  1. Open the script project.
  2. At the left, click Project Settings .
  3. Select the Show "appsscript.json" manifest file in editor checkbox.
  4. At the left, click Editor .
  5. At the left, click the appsscript.json file.
  6. Locate the top-level field labeled oauthScopes. If it's not present, you can add it.
  7. 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"
        ],
       ...
      }
  8. At the top, click 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.