Troubleshooting Shared Drive API 403: insufficientFilePermissions

When your script, service account, or application issues a request to the Google Drive API v3 (or v2) targeting a file or folder inside a Shared Drive, the call may fail with an HTTP 403 Forbidden response containing the error reason: insufficientFilePermissions.

This indicates that while your OAuth authentication token is valid, the acting identity does not have the required access level on the file, the drive container, or the specific operation requested.

{
  "error": {
    "code": 403,
    "message": "The user does not have sufficient permissions for this file.",
    "errors": [
      {
        "message": "The user does not have sufficient permissions for this file.",
        "domain": "global",
        "reason": "insufficientFilePermissions"
      }
    ]
  }
}

Quick Answer

The insufficientFilePermissions error occurs when your API call lacks the query parameter supportsAllDrives=true, the authenticated account holds an insufficient Shared Drive role for the requested operation, or an organizational policy blocks the action. Add supportsAllDrives=true to your request parameters and verify that the user or service account has Content Manager or Manager permissions.

---

Diagnostic Distinction: insufficientPermissions vs. insufficientFilePermissions

Understanding the exact error string saves hours of debugging:

• insufficientPermissions (No “File” in string): This points to an OAuth scope issue. Your API token was minted without the necessary scopes (e.g., calling files.delete with only https://www.googleapis.com/auth/drive.readonly).
• insufficientFilePermissions: Your OAuth scope is adequate, but the Access Control List (ACL) or role on the target file/Shared Drive forbids the operation.

---

Root Causes and How to Resolve Them

1. Missing supportsAllDrives=true in Request Parameters

When interacting with files inside Shared Drives, standard Drive API v3 endpoints (such as files.get, files.update, files.delete, files.copy, and permissions.create) require explicit opt-in parameters. If your application omits these flags, the API may treat the call as targeting personal Drive space and reject operations on Shared Drive files.

• Fix: Ensure the following query parameters are appended to your API request:
  • For single file operations: supportsAllDrives=true (or legacy supportsTeamDrives=true in API v2).
  • For search/listing endpoints (files.list): includeItemsFromAllDrives=true AND supportsAllDrives=true.

// Example: Google APIs Node.js Client
const res = await drive.files.update({
  fileId: '0B5xAIkVXXXXXXXXX',
  supportsAllDrives: true, // Required for Shared Drive files
  requestBody: {
    name: 'Updated_Report.pdf'
  }
});

2. Shared Drive Role Mismatch

Operations in a Shared Drive require specific role capabilities. If your authenticated user or service account is configured with a role that is too restrictive, the API throws insufficientFilePermissions.

Requested API Operation	Minimum Required Role	Common Cause of 403
files.get (Read metadata/content)	Viewer	User is not added to the Shared Drive and non-member sharing is blocked.
files.create / files.update	Contributor	User only has Commenter or Viewer status.
files.delete (Permanent delete)	Manager	Attempting to permanently delete an item with a Content Manager or Contributor role.
Trashing a file (trashed: true)	Content Manager	User is only a Contributor. Contributors cannot move items to Trash.
Moving files between folders	Content Manager	Moving files requires Content Manager rights in both source and destination folders.
permissions.create (Sharing)	Manager	Only Managers can adjust membership or share items when restricted.

If you are seeing permission conflicts between operational roles, read Fix: “Manager” vs. “Content Manager” Conflict” and Why “Delete” is Grayed Out in a Google Shared Drive.

3. Service Account Is Not a Member of the Shared Drive

A common misconception in backend automation is assuming a Google Cloud Service Account with Editor or Owner privileges on the Cloud Project automatically inherits access to company Drive files.

Service accounts act as distinct users with unique email addresses (name@project-id.iam.gserviceaccount.com).

• Fix: Open the Shared Drive in the web UI, click Manage members, and explicitly add the service account’s client email with the appropriate role (Content Manager or Manager).
• For detailed configuration when using service identities, see How to Resolve “Service Account cannot access Drive”.

4. File-Specific Capability Locks

Even if a user holds a valid role, specific file metadata settings can prevent modification. For example, if a file has capabilities.canEdit: false due to an administrator Data Loss Prevention (DLP) lock, legal hold, or container restriction, the API will reject edit attempts.

Inspect the resource’s effective capabilities by calling files.get with field filtering:

GET <https://www.googleapis.com/drive/v3/files/[FILE_ID]?fields=capabilities,driveId&supportsAllDrives=true>

Check the returned JSON for:

• canTrash: whether the current identity can move the file to the Shared Drive trash.
• canDelete: whether the identity can purge the file.
• canEdit: whether metadata and file streams can be updated.

5. Container Settings Disallow Moving Items Out

If your script attempts to move a file out of a Shared Drive into a user’s personal Drive by modifying the addParents and removeParents parameters in files.update, the call fails with a 403 if the Shared Drive has settings that restrict file exfiltration.

Review the restrictions detailed in Why “Prevent non-members from accessing files” is breaking flow and Fix: “You are not allowed to move items out of this Drive”.

---

Step-by-Step API Triage Flowchart

If the error persists after confirming the parameter flags:

1. Verify Identity: Log the output of about.get(fields="user") to ensure the API is running under the identity you expect.
2. Check Membership: Call permissions.list on the Shared Drive container ID (fileId=[sharedDriveId]&supportsAllDrives=true) to verify the acting identity’s explicit role.
3. Verify Manifest / Apps Script Scopes: If running inside an Apps Script project, verify in appsscript.json that your script has requested full Drive scope (https://www.googleapis.com/auth/drive) rather than a restrictive scope like drive.file. See Fix: “Script not authorized to access Google Drive”.
4. Isolate the Action: Test whether a basic read (files.get) succeeds on the same file. If reading succeeds but updating or trashing fails, the issue is strictly a role tier mismatch. Upgrade the acting user to Content Manager or Manager.