Currentonly Scopes in Google Apps Script

When developing with Google Apps Script, managing permissions is crucial for both security and user trust. One of the most effective ways to limit your script’s reach is by using “currentonly” scopes. This tells Google (and your users) that your script only needs to access the specific file it is running in, rather than having full access to the user’s entire Google Drive.

However, this restricted scope comes with significant limitations that often trip up developers. This post breaks down what it is, how to use it, and where it fails.

What is @OnlyCurrentDoc?

By default, if you use a method like SpreadsheetApp.getActiveSpreadsheet(), Apps Script might request a broad scope like https://www.googleapis.com/auth/spreadsheets. This scope grants your script access to read and write every single spreadsheet in the user’s Google Drive.

That’s often overkill. If you are building a simple script bound to a specific sheet, you likely only need access to that sheet.

To restrict this, you can add a JSDoc annotation at the top of your script file:

/**
 * @OnlyCurrentDoc
 */

function onOpen() {
  // ...
}

When you save your script, Apps Script attempts to narrow the required scopes to their .currentonly variants, such as https://www.googleapis.com/auth/spreadsheets.currentonly.

The Benefits

1. Security: If your script is compromised or contains a bug, the damage is limited to the single file it’s running in.
2. User Trust: The authorization dialog is much less scary. Instead of asking to “See, edit, create, and delete all your Google Sheets spreadsheets,” it asks to “See, edit, create, and delete this spreadsheet.”

The Critical Limitations

While powerful, currentonly scopes are not a magic bullet. They have specific constraints that, if ignored, will cause your script to fail with permission errors.

1. Only works with Built-in Services

The currentonly model is designed for the high-level, built-in Apps Script services:

• SpreadsheetApp
• DocumentApp
• SlidesApp
• FormApp

If you stick to methods like SpreadsheetApp.getActiveSpreadsheet(), you are golden.

2. No Access to openById or openByUrl

This is the most common point of confusion. The currentonly scope literally means current only.

If you try to access another file:

// This will FAIL if @OnlyCurrentDoc is present
const otherSheet = SpreadsheetApp.openById("12345...");

Your script will throw an error stating it does not have permission to perform that action. You restricted it to the active doc, so it cannot open others.

3. Does NOT work with Advanced Services

This is a big one. Advanced Google Services (enabled under “Services” in the editor, like Sheets for the Sheets API v4) do not support currentonly scopes.

If you enable the Sheets Advanced Service to use functionality not available in SpreadsheetApp (like certain developer metadata operations or complex formatting), your script will require the full https://www.googleapis.com/auth/spreadsheets scope.

4. Does NOT work with Direct API Calls

Similarly, if you are using UrlFetchApp to manually call the Google Drive API or Google Sheets API with an OAuth token:

ScriptApp.getOAuthToken();
UrlFetchApp.fetch("https://sheets.googleapis.com/v4/...");

You need the full scope associated with that API endpoint. The currentonly scope is an Apps Script concept, not a general Google API concept that can be passed to raw REST endpoints easily in this context.

Summary

Use currentonly scopes whenever possible to improve security and user experience. But remember:

• Do use it for container-bound scripts that only modify the active file.
• Don’t expect it to work if you need to open other files (openById).
• Don’t expect it to work with Advanced Services (Sheets, Drive, etc.).