When you run a Google Apps Script and see a message like “Authorization required” or “Missing permission”, the problem is usually not your code – it’s the set of permissions (also called scopes) that the project has been granted. This article helps you understand exactly what permissions a script needs, how to verify them, and how to fix common mismatches before they block your web app or trigger.
Why Apps Script Permissions Matter
Every Apps Script runs under the identity of the user who authorises it. Google protects user data by limiting what a script can do unless the user explicitly grants the required access. Permissions are defined in the project’s appsscript.json manifest as oauthScopes. If a scope is missing, the script stops with an authorization error; if a scope is unnecessary, you expose more data than needed, which can raise security concerns during reviews.
Diagnosing Permission Issues
Follow this diagnostic path to pinpoint the root cause.
- Reproduce the error. Run the function that fails and note the exact message shown in the dialog or in the execution log.
- Check the execution log. Open View → Logs or the Apps Script dashboard. Look for lines that mention Missing required scope or Authorization is required.
- Identify the API used. Which Google service does the failing line call? Common services include:
- SpreadsheetApp – needs https://www.googleapis.com/auth/spreadsheets (read/write) or the more limited .../readonly.
- GmailApp – needs https://mail.google.com/.
- UrlFetchApp – needs https://www.googleapis.com/auth/script.external_request.
- Open the manifest. In the script editor, click the three‑dot menu → Project Settings** → **Show "appsscript.json"**. Review the oauthScopes array.
- Compare required vs. declared scopes. If a required scope is missing, add it; if an extra scope is present, consider removing it after confirming it isn’t needed.
- Re‑authorise the script. After editing the manifest, click Deploy → Test deployments (or simply run any function). Google will prompt the user to grant the new scopes.
Step‑by‑Step: Setting the Correct Permissions
Before you start, make sure you have:
- A Google account with edit access to the script project.
- Owner or editor rights on any Google Sheets, Docs, or other files the script will touch.
- APIs that your script uses are enabled in the Google Cloud console (e.g., Gmail API, Drive API).
Then follow these steps:
- Enable required APIs. Go to Google Cloud Console → APIs & Services → Library. Search for each service (e.g., "Gmail API", "Google Sheets API") and click **Enable**.
- Open the manifest. In the Apps Script editor, click the gear icon → Project Settings** → **Show "appsscript.json"**.
- Add missing scopes. Insert the needed scopes inside the oauthScopes array. Example: { "timeZone": "America/New_York", "exceptionLogging": "STACKDRIVER", "oauthScopes": [ "https://www.googleapis.com/auth/spreadsheets", "https://mail.google.com/", "https://www.googleapis.com/auth/script.external_request" ] }
- Save the manifest. Click **Save** (Ctrl + S). The editor validates JSON; fix any syntax errors before proceeding.
- Deploy or run to trigger re‑authorization. Choose **Run → anyFunction** or **Deploy → New deployment**. The consent screen will list the new scopes; click **Allow**.
- Test the workflow. Execute the function that previously failed. If it runs without an authorization error, the permission issue is resolved.
Hypothetical Example
Imagine you built a simple inventory‑update script that:
- Reads product quantities from a Google Sheet (SpreadsheetApp).
- Sends a low‑stock alert email (GmailApp).
- Calls an external pricing API (UrlFetchApp).
The script fails on the first line with “Authorization is required”. Your manifest currently contains only the default scope https://www.googleapis.com/auth/script.scriptapp. To fix it:
- Enable the Google Sheets API and Gmail API in the Cloud console.
- Add the following scopes to appsscript.json: "https://www.googleapis.com/auth/spreadsheets", "https://mail.google.com/", "https://www.googleapis.com/auth/script.external_request"
- Save, then run the script. The user sees a consent screen listing "View and manage your spreadsheets in Google Drive" and "Send email as you". After allowing, the script proceeds without errors.
Common Mistakes and How to Fix Them
- Over‑scoping. Adding broad scopes like https://www.googleapis.com/auth/drive when only spreadsheet access is needed. Fix: Replace with the most specific scope (e.g., spreadsheets).
- Missing simple‑trigger vs. installable‑trigger confusion. Simple triggers (e.g., onEdit) run under the owner's account and cannot request additional scopes. Fix: Convert to an installable trigger via ScriptApp.newTrigger(...).forSpreadsheet(...).onEdit().create(), then grant the needed scopes.
- Forgetting to enable the API. Adding a scope but not enabling the corresponding API results in “Service not enabled” errors. Fix: Enable the API in the Cloud console.
- Using a shared Google Sheet without proper sharing. The script runs, but the user lacks edit rights, causing “You do not have permission to call SpreadsheetApp.openById”. Fix: Share the sheet with the script author or use a service account where appropriate.
- Not re‑authorising after scope changes. Updating the manifest does not automatically refresh the consent. Fix: Run any function or redeploy the web app to force a new consent prompt.
Practical Checklist for Permissions
- ☑ Identify every Google service your script calls.
- ☑ List the official OAuth scope for each service (see the Google Apps Script documentation).
- ☑ Open appsscript.json and ensure each required scope is present.
- ☑ Enable the matching APIs in Google Cloud Console.
- ☑ Verify file sharing settings for any external Sheets, Docs, or Drive files.
- ☑ Deploy or run the script to trigger the consent screen.
- ☑ Test all functions, especially those that run on triggers or as a web app.
- ☑ Review the consent screen regularly; remove scopes that are no longer needed.
FAQs
Q: Do I need to add scopes for every single line of code?
Only for the services you actually call. If a function is never executed, its scopes are not required.
Q: Can I hide scopes from the user?
No. Google’s consent screen always shows the full list of scopes a script requests. Over‑scoping may cause users to reject the app.
Q: What if a user revokes a permission later?
When a revoked scope is needed, the script will throw an authorization error. Prompt the user to re‑authorise, or catch the error and display a friendly message.
Understanding and managing Apps Script permissions is a small step that prevents big roadblocks. By following the diagnostic path, updating the manifest, and testing carefully, you can keep your web app or automation running smoothly.
Next step: Review your current script’s manifest, add any missing scopes, and re‑authorise the project. If you hit a wall, tell Nextpath Solutions your goal, what you have already tried and the main blocker. We can help you identify a suitable next step.
Looking for a ready‑made solution? View the Apps Script ecommerce source‑code package and ask about deployment or custom workflow support.