Share files and folders

To share files and folders, permissions are used. Access to files & folders is determined by an access control list (ACL). An ACL is a list of permissions that determine whether or not users can perform actions on a file such as read or write.

See the reference guide for more information about permissions.

Retrieve permissions

Use the permissions.list to retrieve permissions for an item in Drive.

Verify permission to open a file

When opening files, your app should check the user’s permission, and render the UI appropriately, disabling edit for users with only read or comment privileges.

Permissions in Team Drives

The role and additionalRoles fields of a permission reflect the effective roles the user, group, or domain have for a given item. To determine the source of the effective roles, use the teamDrivePermissionDetails field. This field enumerates all inherited and direct file permissions for the user, group, or domain.

Manipulating permissions

Use permissions.insert to grant additional permissions to a user, group, or domain. To change the assigned role, permissions.update.

Permissions may be granted on individual items in a Team Drive even if the target user or group is already a member. If the new role is more permissive than the role granted via their membership, the new permission becomes the effective role for the selected items.

Revoking access

To revoke access to an item, delete the permission. This is also used to delete any direct file access permissions on a Team Drive item.

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

For items in a Team Drive, inherited permissions can not be revoked. Update or revoke the permission on the parent item instead.

Transferring ownership

To transfer ownership of a file, insert or update a permission with the owner role and set the transerOwnership query parameter to true. When a file is transferred, the previous owner's role is downgraded to writer.

Ownership transfers are not supported for items in Team Drives. Ownership transfers are implicit when a user moves an item in or out of a Team Drive.

Manipulating permissions with batch requests

We strongly recommend using batch requests to modify multiple permissions.

Examples

Here are examples of performing a batch permission modification with our Drive API client libraries.

Java

String fileId = "1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ";
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());
  }
};
BatchRequest batch = driveService.batch();
Permission userPermission = new Permission()
    .setType("user")
    .setRole("writer")
    .setValue("user@example.com");
driveService.permissions().insert(fileId, userPermission)
    .setFields("id")
    .queue(batch, callback);

Permission domainPermission = new Permission()
    .setType("domain")
    .setRole("reader")
    .setValue("example.com");
driveService.permissions().insert(fileId, domainPermission)
    .setFields("id")
    .queue(batch, callback);

batch.execute();

Python

file_id = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ'
def callback(request_id, response, exception):
    if exception:
        # Handle error
        print exception
    else:
        print "Permission Id: %s" % response.get('id')

batch = drive_service.new_batch_http_request(callback=callback)
user_permission = {
    'type': 'user',
    'role': 'writer',
    'value': 'user@example.com'
}
batch.add(drive_service.permissions().insert(
        fileId=file_id,
        body=user_permission,
        fields='id',
))
domain_permission = {
    'type': 'domain',
    'role': 'reader',
    'value': 'example.com'
}
batch.add(drive_service.permissions().insert(
        fileId=file_id,
        body=domain_permission,
        fields='id',
))
batch.execute()

PHP

$fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
$driveService->getClient()->setUseBatch(true);
try {
    $batch = $driveService->createBatch();

    $userPermission = new Google_Service_Drive_Permission(array(
        'type' => 'user',
        'role' => 'writer',
        'value' => 'user@example.com'
    ));
    $request = $driveService->permissions->insert(
        $fileId, $userPermission, array('fields' => 'id'));
    $batch->add($request, 'user');
    $domainPermission = new Google_Service_Drive_Permission(array(
        'type' => 'domain',
        'role' => 'reader',
        'value' => 'example.com'
    ));
    $request = $driveService->permissions->insert(
        $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);
        }
    }
} finally {
    $driveService->getClient()->setUseBatch(false);
}

.NET

var fileId = "1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ";
var batch = new BatchRequest(driveService);
BatchRequest.OnResponse<Permission> callback = delegate (
    Permission permission,
    RequestError error,
    int index,
    System.Net.Http.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",
    Value = "user@example.com"
};
var request = driveService.Permissions.Insert(userPermission, fileId);
request.Fields = "id";
batch.Queue(request, callback);

Permission domainPermission = new Permission()
{
    Type = "domain",
    Role = "reader",
    Value = "example.com"
};
request = driveService.Permissions.Insert(domainPermission, fileId);
request.Fields = "id";
batch.Queue(request, callback);
var task = batch.ExecuteAsync();

Ruby

file_id = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ'
callback = lambda do |res, err|
  if err
    # Handle error...
    puts err.body
  else
    puts "Permission ID: #{res.id}"
  end
end
drive_service.batch do
  user_permission = {
      type: 'user',
      role: 'writer',
      value: 'user@example.com'
  }
  drive_service.insert_permission(file_id,
                                  user_permission,
                                  fields: 'id',
                                  &callback)
  domain_permission = {
      type: 'domain',
      role: 'reader',
      value: 'example.com'
  }
  drive_service.insert_permission(file_id,
                                  domain_permission,
                                  fields: 'id',
                                  &callback)
end

Node.js

var fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
var permissions = [
  {
    'type': 'user',
    'role': 'writer',
    'value': 'user@example.com'
  }, {
    'type': 'domain',
    'role': 'writer',
    'value': 'example.com'
  }
];
// Using the NPM module 'async'
async.eachSeries(permissions, function (permission, permissionCallback) {
  drive.permissions.insert({
    resource: permission,
    fileId: fileId,
    fields: 'id',
  }, function (err, res) {
    if (err) {
      // Handle error...
      console.error(err);
      permissionCallback(err);
    } else {
      console.log('Permission ID:', res.id)
      permissionCallback();
    }
  });
}, function (err) {
  if (err) {
    // Handle error
    console.error(err);
  } else {
    // All permissions inserted
  }
});

Understand how the permissions work

Lists of permissions are available for each file and folder in Drive. Each permission specifies a type, role, and emailAddress or domain, permitting a level of access to a file or folder. These values work together to limit the access appropriately. The type limits access to a set of users. The email address and domain fields specify which users can have access. Finally, the role gives these users the ability to do something to the file, like read it. When combined, these properties define a complete permission.

Roles

Each permission in the Google Drive API has a role. A role defines what users can do with a file. The following table describes what operations users in each role can perform.

Permitted operation organizer/owner fileOrganizer writer commenter reader
Read the metadata (e.g. name, description) of the file or folder
Read the content of the file
Read the list of items in the folder
Add comments to the file
Modify the metadata of the file or folder
Modify the content of the file
Access historical revisions
Add items to the folder
Remove items from the My Drive folder
Share a Team Drive item
Add files to Team Drives
Move items into the Trash
Reorganize items within a Team Drive1
Move items outside of a Team Drive2
Delete the file or folder
Delete items in Team Drives2
Edit Team Drive metadata
Add Team Drive members
Delete an empty Team Drive

Types and values

Every permission of a file or folder has a type. The type is the scope of the permission, and determines which users have a role. Permissions with types user and groups also have an emailAddress. Permissions with type domain have a corresponding domain property that specifies the domain name. For example, a permission with a type of domain may have a domain of thecompany.com, indicating that the permission grants the given role to all users in the G Suite domain thecompany.com. The following table shows which types and values are possible.

Type Field Possible values
user emailAddress Email address of a user. Example: joe@thecompany.com
group emailAddress Email address of a Google Group. Example: admins@thecompany.com
domain domain Domain name of G Suite domain. Example: thecompany.com
anyone N/A The anyone permission does not require an emailAddress or domain field.

IDs and names

The id is always the unique identifier of the value of the permission. IDs should be treated as opaque values.

The displayName is always the "pretty" name of the value of the permission. The following is a list of potential names for each type of permission.

Type Possible name values
user User's full name, as defined for their Google account. Example: Joe Smith
group Name of the Google Group. Example: The Company Administrators
domain String domain name. Example: thecompany.com
anyone No displayName is present.

Parent-child propagation

ACLs set on folders propagate downward to all contained items. Propagation occurs whenever permissions or the hierarchy are changed, and is done recursively through all nested folders.

Inherited permissions cannot be removed from an item in a Team Drive. Instead they can be adjusted on the direct or indirect parent from which it was inherited. Inherited permissions may be removed from items under "My Drive" or "Shared with me."

Capabilities

The effective permissions for the current user are represented as capabilities in the file metadata. Capabilities are a collection of boolean fields that indicate whether or not an action can be performed on the file.

Send feedback about...

Drive REST API v2
Drive REST API v2
Need help? Visit our support page.