Masquer
Apps Script

Authorization for Google Services

Apps Script requires user authorization to access private data from built-in Google services or advanced Google services.

Granting access rights

If a script uses services that can access private data, you'll see one of the sets of authorization dialogs below. Apps Script determines the authorization scopes (like access your Google Sheets files or Gmail) automatically, based on a scan of the code. Code that is commented out still generates an authorization request.

Scripts that you have previously authorized will also ask for additional authorization if a code change adds new services. Scripts do not request authorization if they use only services that cannot access user data (like the URL Fetch service or the Language service), or if you access the script as a web app that runs under the script owner's user identity.

Current authorization dialogs Old authorization dialogs

Revoking access rights

To revoke a script's access to your data, follow these steps:

  1. Visit the permissions page for your Google account. (To navigate to this page in the future, visit Google.com, then click your account picture in the top-right corner of the screen. Next, click Account, then Security, then View all in the account permissions section.)
  2. Click the name of the script whose authorization you want to revoke, then click Revoke access on the right.

Permissions and types of scripts

The user identity that a script runs with — and thus the data it can access — varies based on the scenario in which the script is run, as shown in the table below.

Type of script Script runs as...
Standalone, add-on, or bound to Docs, Sheets, or Forms User at the keyboard
Custom function in a spreadsheet Anonymous user; however, quota limits count against user at the keyboard
Web app or Google Sites gadget User at the keyboard or script owner, dependent on options selected when deploying the app
Installable trigger User who created the trigger

Manual authorization scopes for Sheets, Docs, and Forms

If you're building an add-on or other script that uses the Spreadsheet service, Document service, or Forms service, you can force the authorization dialog to ask only for access to files in which the add-on or script is used, rather than all of a user's spreadsheets, documents, or forms. To do to, include the following JsDoc annotation in a file-level comment:

/**
 * @OnlyCurrentDoc
 */

An opposing annotation, @NotOnlyCurrentDoc, is available if your script includes a library that declares @OnlyCurrentDoc, but the master script actually requires access to more than the current file.

Authorization lifecycle for add-ons

Add-ons for Google Sheets, Docs, and Forms generally follow the same authorization model as scripts that are bound to a document. In certain circumstances, however, their onOpen(e) and onEdit(e) functions run in a no-authorization mode that presents some additional complications. For more information, see the guide to the add-on authorization lifecycle.

Using a different Google Developers Console project

Every Apps Script project automatically creates its own project in the Google Developers Console to control authorization. (Unlike a regular Developers Console project, you access this project by selecting Resources > Developers Console Project, then clicking the name of the project, which will be something like [Script Name] - api-project-123456789012. Do not click "View Developers Console", because that page does not show Apps Script projects.)

If you want to authorize a script at the same time as another app that uses Google APIs, you can change the Developers Console project that your script relies on so that it shares with the other app. This feature is most commonly used to bundle an add-on with a Google Apps Marketplace app.

To change a script's Developers Console project and delete the old Developers Console project, follow these steps:

  1. Look up the project number (not name) of the Developers Console project that you want to switch to. To do this, open the Google Developers Console, click the project's name, and copy the Project Number from the top of the screen.
  2. Open the script whose Developer Console project you want to delete and replace.
  3. Click Resources > Developers Console Project.
  4. Paste the project number from step 1 into the text field, then click Set Project.
  5. A warning screen will explain the effects of changing the Developers Console project. Read the notice carefully, then enter the old project number from the last sentence of the warning (in bold) into the text field and click Confirm.

Upgrading authorization experience

By default, scripts created before July 2013 use an older version of the authorization flow. To upgrade a script to the new flow, select File > Upgrade authorization experience. As the confirmation dialog warns, upgrading to the new flow has a few side effects:

  • Each existing user of the script will be prompted to reauthorize. (If you run the script on a trigger instead of directly, you'll still need to reauthorize it.)
  • Any advanced Google services used by the script will need to be enabled again in the Google Developers Console.
  • Upgrading to the new flow is irreversible.