Share files, folders and drives

Every Google Drive file, folder, and shared drive has associated Permissions resources. Each resource identifies the permission for a specific type (user, group, domain, anyone) and role, such as "commenter" or "reader." For example, a file might have a permission granting a specific user (type=user) the read-only access (role=reader) while another permission grants members of a specific group (type=group) the ability to add comments to the file (role=commenter).

To share a file or folder, the user must have the role of "writer." To share (add a member to) a shared drive , the user must have the role of "organizer."

For a complete list of roles and the operations permitted by each, refer to Roles.

Permission propagation

Permission lists for a folder propagate downward and are inherited by all child files and folders. Whenever permissions or the hierarchy is changed, the propagation occurs recursively through all nested folders. For example, if a file exists in a folder and that folder is then moved within another folder, the permissions on the new folder propagates to the file. If the new folder grants the user of the file a new role, such as "writer," it overrides their old role.

Conversely, if a file inherits the "writer" role from a folder, and is moved to another folder that provides a "reader" role, the file now inherits the "reader" role.

Inherited permissions can't be removed from a file or folder in a shared drive. Instead these permissions must be adjusted on the direct or indirect parent from which they were inherited. Inherited permissions can be removed from items under "My Drive" or "Shared with me."

Conversely, inherited permissions can be overridden on a file or folder on a My Drive. So, if a file inherits the role of "writer" from a My Drive folder, you can set the role of "reader" on the file to lower its permission level.

Capabilities

The permission resource doesn't ultimately determine the current user's ability to perform actions on a file or folder. Instead, a Files resource contains a collection of boolean capabilities fields used to indicate if an action can be performed on a file or folder. These fields are set by the Google Drive API based on the current user's Permissions resource associated with the file or folder.

For example, when Jon logs into your app and tries to share a file, Jon's role is checked in terms of permissions to the file. If his role enables him to share a file, the capabilities related to the file, such as canShare are filled in relative to the role. Then when Jon wants to share the file, your app would check the capabilities to ensure canShare is set to true.

Create a permission

The following two fields are necessary when creating a permission:

  • type. The type identifies the scope of the permission (user, group, domain, or anyone). A permission with a type of user applies to a specific user whereas a permission with a type of domain applies to everyone in a specific domain.

  • role. The role field identifies the operations that the type can perform. For example, a permission with a type of user and a role of reader grants a specific user read-only access to the file or folder. Or, a permission with a type of domain and the role of commenter grants everyone in the domain the ability to add comments to a file. For a complete list of roles and the operations permitted by each, refer to Roles.

When you create a permission where type is user or group, you must also provide an emailAddress to tie the specific user or group to the permission.

When you create a permission where type is domain, you must also provide a domain to tie a specific domain to the permission.

To create a permission:

  1. Use the Permissions.create method with the fileId for the associated file or folder.
  2. In the request, identify the type and role.
  3. If the type is user or group, provide an emailAddress. If the type is domain, provide a domain.

Retrieve all permissions for a file, folder, or shared drive

Use the Permissions.list to retrieve all permissions for a file, folder, or shared drive.

Verify user permissions

When your app opens a file, it should check the file's capabilities and render the UI to reflect the permissions of the current user. For example, if the user doesn't have a 'canComment' capability on the file, the ability to comment should be disabled in the UI.

To check the capabilities, call files.get with the fileId and fields parameter set to the capabilities field to verify.

For further information on returning fields using the fields parameter, refer to Return specific fields for a file.

Determine the source of the role for shared drive files and folders

To change the role on a file or folder, you need to know the source of the role. For shared drives, the source of a role can be based on membership to the shared drive, the role on a folder, or the role on a file.

To determine the source of the role for a shared drive or items within that drive, use the permissionDetails field.

This field enumerates all inherited and direct file permissions for the user, group, or domain.

Change permissions

To change permissions on a file or folder, change the assigned role. To change the assigned role:

  1. Call permissions.update with permissionId of the permission to change and the fileId for the associated file, folder, or shared drive.

  2. In the request, identify the new role.

Permissions can be granted on individual files or folders in a shared drive even if the user or group is already a member. For example, Jon has the role of commenter as part of membership to a shared drive. However, your app can grant Jon the writer role for a file in a shared drive. In this case, because the new role is more permissive than the role granted using their membership, the new permission becomes the effective role for the file or folder.

Revoke access to a file or folder

To revoke access to an file or folder, call delete to delete the permission.

For items in "My Drive," it is possible to delete an inherited permission. Deleting an inherited permission revokes access to the item and child items, if any.

For items in a shared drive, inherited permissions can not be revoked. Update or revoke the permission on the parent file or folder instead.

The delete operation is also used to delete any permissions directly applied to a shared drive file or folder.

Transfer file ownership to another Google Workspace account in the same organization

Ownership of files existing in "My Drive" can be transferred from one Google Workspace account to another account in the same organization. Files existing in a shared drive are owned by the organization that owns the shared drive. Therefore, ownership transfers are not supported for files and folders in shared drives. Organizers of a shared drive can move items from that shared drive and into their own "My Drive" which transfers the ownership to them.

To transfer ownership of a file in "My Drive," create or update the file's permission with the owner role and set the transferOwnership query parameter to true. When a file is transferred, the previous owner's role is downgraded to writer.

Transfer file ownership from one consumer account to another consumer account

Ownership of files can be transferred between one consumer account to another consumer account. However, drive doesn't transfer ownership of a file between two consumer accounts until the prospective new owner has explicitly consented to the transfer. To transfer file ownership from one consumer account to another consumer account:

  1. The current owner initiates an ownership transfer by creating or updating the prospective new owner's file permission. The permission must include these settings: role=writer, type=user, and pendingOwner=true. If the new owner is creating a new permission for the prospective owner, an email notification is sent to the prospective new owner indicating that they are being asked to assume ownership of the file.

  2. The new owner accepts the ownership transfer request by creating or updating their file permission (from step 1). The permission must include these settings: role=owner and transferOwnership=true. If the new owner is creating a new permission, an email notification is sent to the previous owner indicating that ownership has been transferred.

When a file is transferred, the previous owner's role is downgraded to writer.

Change multiple permissions with batch requests

We strongly recommend using batch requests to modify multiple permissions.

Following is an example of performing a batch permission modification with a client library.

Java

drive/snippets/drive_v3/src/main/java/ShareFile.java
import com.google.api.client.googleapis.batch.BatchRequest;
import com.google.api.client.googleapis.batch.json.JsonBatchCallback;
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpHeaders;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.Permission;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate use-case of modify permissions. */
public class ShareFile {

  /**
   * Batch permission modification.
   * realFileId file Id.
   * realUser User Id.
   * realDomain Domain of the user ID.
   *
   * @return list of modified permissions if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static List<String> shareFile(String realFileId, String realUser, String realDomain)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
         TODO(developer) - See https://developers.google.com/identity for
         guides on implementing OAuth2 for your application.application*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    final List<String> ids = new ArrayList<String>();


    JsonBatchCallback<Permission> callback = new JsonBatchCallback<Permission>() {
      @Override
      public void onFailure(GoogleJsonError e,
                            HttpHeaders responseHeaders)
          throws IOException {
        // Handle error
        System.err.println(e.getMessage());
      }

      @Override
      public void onSuccess(Permission permission,
                            HttpHeaders responseHeaders)
          throws IOException {
        System.out.println("Permission ID: " + permission.getId());

        ids.add(permission.getId());

      }
    };
    BatchRequest batch = service.batch();
    Permission userPermission = new Permission()
        .setType("user")
        .setRole("writer");

    userPermission.setEmailAddress(realUser);
    try {
      service.permissions().create(realFileId, userPermission)
          .setFields("id")
          .queue(batch, callback);

      Permission domainPermission = new Permission()
          .setType("domain")
          .setRole("reader");

      domainPermission.setDomain(realDomain);

      service.permissions().create(realFileId, domainPermission)
          .setFields("id")
          .queue(batch, callback);

      batch.execute();

      return ids;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to modify permission: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/share_file.py
from __future__ import print_function

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def share_file(real_file_id, real_user, real_domain):
    """Batch permission modification.
    Args:
        real_file_id: file Id
        real_user: User ID
        real_domain: Domain of the user ID
    Prints modified permissions

    Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity
    for guides on implementing OAuth2 for the application.
    """
    creds, _ = google.auth.default()

    try:
        # create drive api client
        service = build('drive', 'v3', credentials=creds)
        ids = []
        file_id = real_file_id

        def callback(request_id, response, exception):
            if exception:
                # Handle error
                print(exception)
            else:
                print(f'Request_Id: {request_id}')
                print(F'Permission Id: {response.get("id")}')
                ids.append(response.get('id'))

        # pylint: disable=maybe-no-member
        batch = service.new_batch_http_request(callback=callback)
        user_permission = {
            'type': 'user',
            'role': 'writer',
            'emailAddress': 'user@example.com'
        }
        batch.add(service.permissions().create(fileId=file_id,
                                               body=user_permission,
                                               fields='id',))
        domain_permission = {
            'type': 'domain',
            'role': 'reader',
            'domain': 'example.com'
        }
        domain_permission['domain'] = real_domain
        batch.add(service.permissions().create(fileId=file_id,
                                               body=domain_permission,
                                               fields='id',))
        batch.execute()

    except HttpError as error:
        print(F'An error occurred: {error}')
        ids = None

    return ids


if __name__ == '__main__':
    share_file(real_file_id='1dUiRSoAQKkM3a4nTPeNQWgiuau1KdQ_l',
               real_user='gduser1@workspacesamples.dev',
               real_domain='workspacesamples.dev')

Node.js

drive/snippets/drive_v3/file_snippets/share_file.js
/**
 * Batch permission modification
 * @param{string} fileId file ID
 * @param{string} targetUserEmail username
 * @param{string} targetDomainName domain
 * @return{list} permission id
 * */
async function shareFile(fileId, targetUserEmail, targetDomainName) {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');
  const async = require('async');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({scopes: 'https://www.googleapis.com/auth/drive'});
  const service = google.drive({version: 'v3', auth});

  let id;
  const permissions = [
    {
      'type': 'user',
      'role': 'writer',
      'emailAddress': targetUserEmail, // 'user@partner.com',
    }, {
      'type': 'domain',
      'role': 'writer',
      'domain': targetDomainName, // 'example.com',
    },
  ];
  // Using the NPM module 'async'
  try {
    async.eachSeries(permissions, function(permission) {
      service.permissions.create({
        resource: permission,
        fileId: fileId,
        fields: 'id',
      }).then(function(result) {
        id = result.data.id;
        console.log('Permission Id:', id);
      });
    });
    return id;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveShareFile.php
use Google\Client;
use Google\Service\Drive;
function shareFile()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $realFileId = readline("Enter File Id: ");
        $realUser = readline("Enter user email address: ");
        $realDomain = readline("Enter domain name: ");
        $ids = array();
            $fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
            $fileId = $realFileId;
            $driveService->getClient()->setUseBatch(true);
            try {
                $batch = $driveService->createBatch();

                $userPermission = new Drive\Permission(array([
                    'type' => 'user',
                    'role' => 'writer',
                    'emailAddress' => 'user@example.com'
                ]));
                $userPermission['emailAddress'] = $realUser;
                $request = $driveService->permissions->create(
                    $fileId, $userPermission, array(['fields' => 'id']));
                $batch->add($request, 'user');
                $domainPermission = new Drive\Permission(array([
                    'type' => 'domain',
                    'role' => 'reader',
                    'domain' => 'example.com'
                ]));
                $userPermission['domain'] = $realDomain;
                $request = $driveService->permissions->create(
                    $fileId, $domainPermission, array(['fields' => 'id']));
                $batch->add($request, 'domain');
                $results = $batch->execute();

                foreach ($results as $result) {
                    if ($result instanceof Google_Service_Exception) {
                        // Handle error
                        printf($result);
                    } else {
                        printf("Permission ID: %s\n", $result->id);
                        array_push($ids, $result->id);
                    }
                }
            } finally {
                $driveService->getClient()->setUseBatch(false);
            }
            return $ids;
    } catch(Exception $e) {
        echo "Error Message: ".$e;
    }

}

.NET

drive/snippets/drive_v3/DriveV3Snippets/ShareFile.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Drive.v3.Data;
using Google.Apis.Requests;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use-case of Drive modify permissions.
    public class ShareFile
    {
        /// <summary>
        /// Batch permission modification.
        /// </summary>
        /// <param name="realFileId">File id.</param>
        /// <param name="realUser">User id.</param>
        /// <param name="realDomain">Domain id.</param>
        /// <returns>list of modified permissions, null otherwise.</returns>
        public static IList<String> DriveShareFile(string realFileId, string realUser, string realDomain)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var ids = new List<String>();
                var batch = new BatchRequest(service);
                BatchRequest.OnResponse<Permission> callback = delegate(
                    Permission permission,
                    RequestError error,
                    int index,
                    HttpResponseMessage message)
                {
                    if (error != null)
                    {
                        // Handle error
                        Console.WriteLine(error.Message);
                    }
                    else
                    {
                        Console.WriteLine("Permission ID: " + permission.Id);
                    }
                };
                Permission userPermission = new Permission()
                {
                    Type = "user",
                    Role = "writer",
                    EmailAddress = realUser
                };

                var request = service.Permissions.Create(userPermission, realFileId);
                request.Fields = "id";
                batch.Queue(request, callback);

                Permission domainPermission = new Permission()
                {
                    Type = "domain",
                    Role = "reader",
                    Domain = realDomain
                };
                request = service.Permissions.Create(domainPermission, realFileId);
                request.Fields = "id";
                batch.Queue(request, callback);
                var task = batch.ExecuteAsync();
                task.Wait();
                return ids;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}