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.

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, 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 in the Apps Script editor.
  2. In the menu, select File > Project properties.
  3. Select the Scopes tab.

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 and web apps 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 in the Apps Script editor.
  2. In the menu, select File > Project properties.
  3. Select the Scopes tab.
  4. Review the scopes your script currently requires and determine what changes need to be made. Click Cancel when finished.
  5. If the manifest file appsscript.json isn't visible in the left nav bar, select the View > Show manifest file menu item.
  6. Select the appsscript.json file in the left nav to open it.
  7. Locate the top-level field labeled oauthScopes. If it is not present, you can add it.
  8. 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"
      ],
      ...
    }
    
  9. Save the manifest file using Ctrl+S or the Save file icon in the menu bar.

Send feedback about...

Apps Script
Apps Script