Every Google Drive file, folder, and shared drive have associated permissions
resources. Each resource
identifies the permission for a specific type
( user
, group
, domain
, anyone
) and role
( owner
, organizer
, fileOrganizer
, writer
, commenter
, reader
). For example, a
file might have a permission granting a specific user ( type=user
) read-only
access ( role=reader
) while another permission grants members of a specific
group ( type=group
) the ability to add comments to a file ( role=commenter
).
For a complete list of roles and the operations permitted by each, see Roles and permissions .
How permissions work
Permission lists for a folder propagate downward. All child files and folders inherit permissions from the parent. 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 propagate to the file. If the new folder grants the file user a new role, such as "writer," it overrides their old role.
Conversely, if a file inherits role=writer
from a folder, and is moved to
another folder that provides a "reader" role, the file now inherits role=reader
.
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 in My
Drive. So, if a file inherits role=writer
from a My
Drive folder, you can set role=reader
on the file to lower its
permission level.
Concurrent permissions operations on the same file aren't supported. Only the last update is applied.
Understand file capabilities
The permissions
resource doesn't ultimately
determine the current user's ability to perform actions on a file or folder.
Instead, the files
resource contains a collection
of boolean capabilities
fields used to indicate whether an action can be performed on a file or folder.
The Google Drive API sets these fields based on the current user's permissions
resource associated with the file or folder.
For example, when Alex logs into your app and tries to share a file, Alex's role
is checked for permissions on the file. If the role allows them to share a file,
the capabilities
related to the file, such as canShare
, are set relative to
the role. If Alex wants to share the file, your app checks the capabilities
to
ensure canShare
is set to true
.
Get file capabilities
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 the canComment
capability on the file, the ability to comment
should be disabled in the UI.
To check the capabilities, call the get
method on the files
resource with the fileId
path parameter and the fields
parameter set to the capabilities
field. For
further information on returning fields using the fields
parameter, see Return specific fields
.
The following code sample shows how to verify user permissions. The response returns a list of capabilities the user has on the file. Each capability corresponds to a fine-grained action that a user can take. Some fields are only populated for items in shared drives.
Request
GET https://www.googleapis.com/drive/v3/files/ FILE_ID
?fields=capabilities
Response
{ "capabilities" : { "canAcceptOwnership" : false , "canAddChildren" : false , "canAddMyDriveParent" : false , "canChangeCopyRequiresWriterPermission" : true , "canChangeItemDownloadRestriction" : true , "canChangeSecurityUpdateEnabled" : false , "canChangeViewersCanCopyContent" : true , "canComment" : true , "canCopy" : true , "canDelete" : true , "canDisableInheritedPermissions" : false , "canDownload" : true , "canEdit" : true , "canEnableInheritedPermissions" : true , "canListChildren" : false , "canModifyContent" : true , "canModifyContentRestriction" : true , "canModifyEditorContentRestriction" : true , "canModifyOwnerContentRestriction" : true , "canModifyLabels" : true , "canMoveChildrenWithinDrive" : false , "canMoveItemIntoTeamDrive" : true , "canMoveItemOutOfDrive" : true , "canMoveItemWithinDrive" : true , "canReadLabels" : true , "canReadRevisions" : true , "canRemoveChildren" : false , "canRemoveContentRestriction" : false , "canRemoveMyDriveParent" : true , "canRename" : true , "canShare" : true , "canTrash" : true , "canUntrash" : true } }
Scenarios for sharing Drive resources
There are five different types of sharing scenarios:
-
To share a file in My Drive, the user must have
role=writerorrole=owner.-
If the
writersCanShareboolean value is set tofalsefor the file, the user must haverole=owner. -
If the user with
role=writerhas temporary access governed by an expiration date and time, they can't share the file. For more information, see Set an expiration date to limit item access .
-
-
To share a folder in My Drive, the user must have
role=writerorrole=owner.-
If the
writersCanShareboolean value is set tofalsefor the file, the user must have the more permissiverole=owner. -
Temporary access (governed by an expiration date and time) is only allowed on folders with
role=reader. For more information, see see Set an expiration date to limit item access .
-
-
To share a file in a shared drive, the user must have
role=writer,role=fileOrganizer, orrole=organizer.- The
writersCanSharesetting doesn't apply to items in shared drives. It's treated as if it's always set totrue.
- The
-
To share a folder in a shared drive, the user must have
role=organizer.- If the
sharingFoldersRequiresOrganizerPermissionrestriction on a shared drive is set tofalse, users withrole=fileOrganizercan share folders in that shared drive.
- If the
-
To manage shared drive membership, the user must have
role=organizer. Only users and groups can be members of shared drives.
Use the fields parameter
If you want to specify the fields to return in the response, you can set the fields
system
parameter
with any method of the permissions
resource. If you omit the fields
parameter, the server returns a default set of fields specific to the method.
For example, the list
method returns
only the id
, type
, kind
, and role
fields for each file. To return
different fields, see Return specific fields
.
Create a permission
The following two fields are necessary when creating a permission:
-
type: Thetypeidentifies the permission scope (user,group,domain, oranyone). A permission withtype=userapplies to a specific user whereas a permission withtype=domainapplies to everyone in a specific domain. -
role: Therolefield identifies operations thetypecan perform. For example, a permission withtype=userandrole=readergrants a specific user read-only access to the file or folder. Or, a permission withtype=domainandrole=commenterlets everyone in the domain add comments to a file. For a complete list of roles and the operations permitted by each, refer to Roles and permissions .
When you create a permission where type=user
or type=group
, you must also
provide an emailAddress
to tie the specific user or group to the permission.
When you create a permission where type=domain
, you must also provide a domain
to tie a
specific domain to the permission.
To create a permission:
- Use the
createmethod on thepermissionsresource with thefileIdpath parameter for the associated file or folder. - In the request body, specify the
typeandrole. - If
type=userortype=group, provide anemailAddress. Iftype=domain, provide adomain.
The following code sample shows how to create a permission. The response returns an instance of a permissions
resource, including the assigned permissionId
.
Request
POST https://www.googleapis.com/drive/v3/files/ FILE_ID
/permissions
{ "requests" : [ { "type" : "user" , "role" : "commenter" , "emailAddress" : "alex@altostrat.com" } ] }
Response
{
"kind"
:
"drive#permission"
,
"id"
:
" PERMISSION_ID
"
,
"type"
:
"user"
,
"role"
:
"commenter"
}
Use target audiences
Target audiences are groups of people—such as departments or teams—that you can recommend for users to share their items with. You can encourage users to share items with a more specific or limited audience rather than your entire organization. Target audiences can help you improve the security and privacy of your data, and make it easier for users to share appropriately. For more information, see About target audiences .
To use target audiences:
-
In the Google Admin console, go to Menu > Directory > Target audiences.
You must be signed in using an account with super administrator privileges for this task.
-
In the Target audiences list, click the name of the target audience. To create a target audience, see Create a target audience
-
Copy the unique ID from the target audience URL:
https://admin.google.com/ac/targetaudiences/ ID. -
Create a permission with
type=domain, and set thedomainfield toID .audience.googledomains.com.
To view how users interact with target audiences, see User experience for link sharing .
Get a permission
To get a permission, use the get
method
on the permissions
resource with the fileId
and permissionId
path parameters. If you don't know the permission
ID, you can list all permissions
using the list
method.
The following code sample shows how to get a permission by ID. The response returns an instance of a permissions
resource.
Request
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissionsPERMISSION_ID
Response
{
"kind"
:
"drive#permissionList"
,
"permissions"
:
[
{
"kind"
:
"drive#permission"
,
"id"
:
" PERMISSION_ID
"
,
"type"
:
"user"
,
"role"
:
"commenter"
}
]
}
List all permissions
To list permissions for a file, folder, or shared drive, use the list
method on the permissions
resource with the fileId
path parameter.
Pass the following query parameters to customize pagination of, or to filter, permissions:
-
pageSize: The maximum number of permissions to return per page. If not set for files in a shared drive, at most 100 results are returned. If not set for files that aren't in a shared drive, the entire list is returned. -
pageToken: A page token, received from a previous list call. Provide this token to retrieve the subsequent page. -
supportsAllDrives: Whether the requesting app supports both My Drives and shared drives. -
useDomainAdminAccess: Set totrueto issue the request as a domain administrator. If thefileIdparameter refers to a shared drive and the requester is an administrator of the domain to which the shared drive belongs. For more information, see Manage shared drives as domain administrators . -
includePermissionsForView: The additional view's permissions to include in the response. Onlypublishedis supported.
The following code sample shows how to get all permissions. The response returns a list of permissions for a file, folder, or shared drive.
Request
GET https://www.googleapis.com/drive/v3/files/ FILE_ID
/permissions
Response
{
"kind"
:
"drive#permissionList"
,
"permissions"
:
[
{
"id"
:
" PERMISSION_ID
"
,
"type"
:
"user"
,
"kind"
:
"drive#permission"
,
"role"
:
"commenter"
}
]
}
Update permissions
To update permissions on a file or folder, you can change the assigned role. For more information on finding the role source, see Determine the role source .
-
Call the
updatemethod on thepermissionsresource with thefileIdpath parameter set to the associated file, folder, or shared drive and thepermissionIdpath parameter set to the permission to change. To find thepermissionId, use thelistmethod on thepermissionsresource with thefileIdpath parameter. -
In the request, identify the new
role.
You can grant permissions on individual files or folders in a shared drive even
if the user or group is already a member. For example, Alex has role=commenter
as part of their membership to a shared drive. However, your app can grant Alex role=writer
for a file in a shared drive. In this case, because the new role
is more permissive than the role granted through their membership, the new
permission becomes the effective role
for the file or folder.
You can apply updates through patch semantics, meaning you can make partial modifications to a resource. You must explicitly set the fields that you intend to modify in your request. Any fields not included in the request retain their existing values. For more information, see Working with partial resources .
The following code sample shows how to change permissions on a file or folder from commenter
to writer
. The response returns an instance of a permissions
resource.
Request
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"requests": [
{
"role": "writer"
}
]
}
Response
{
"kind"
:
"drive#permission"
,
"id"
:
" PERMISSION_ID
"
,
"type"
:
"user"
,
"role"
:
"writer"
}
Determine the role source
To change the role on a file or folder, you must 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 role source for a shared drive, or items within that drive,
call the get
method on the permissions
resource with the fileId
and permissionId
path parameters, and the fields
parameter set to the permissionDetails
field.
To find the permissionId
, use the list
method on the permissions
resource with the fileId
path parameter. To fetch the permissionDetails
field on the list
request, set the fields
parameter to permissions/permissionDetails
.
This field enumerates all inherited and direct file permissions for the user, group, or domain.
The following code sample shows how to determine the role source. The response returns the permissionDetails
of a permissions
resource. The inheritedFrom
field provides the ID of the item from which the permission is inherited.
Request
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true
Response
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": " INHERITED_FROM_ID
",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}
Update multiple permissions with batch requests
We strongly recommend using batch requests to modify multiple permissions.
The following is an example of performing a batch permission modification with a client library.
Java
Python
Node.js
PHP
.NET
Delete a permission
To revoke access to a file or folder, call the delete
method on the permissions
resource with the fileId
and
the permissionId
path parameters set to delete the permission.
For items in "My Drive," it's 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 cannot be revoked. Update or delete the permission on the parent file or folder instead.
The delete
method is also used to delete permissions directly applied to a
shared drive file or folder.
The following code sample shows how to revoke access by deleting a permissionId
. If successful, the response body is an empty JSON object. To confirm the permission is removed, use the list
method on the permissions
resource with the fileId
path parameter.
Request
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
Set an expiration date to limit item access
When you're working with people on a sensitive project, you might want to restrict their access to certain items in Drive after a period of time. For files and folders, you can set an expiration date to limit or remove access to that item.
To set the expiration date:
-
Use the
createmethod on thepermissionsresource and set theexpirationTimefield (along with the other required fields). For more information, see Create a permission . -
Use the
updatemethod on thepermissionsresource and set theexpirationTimefield (along with the other required fields). For more information, see Update permissions .
The expirationTime
field denotes when the permission expires using RFC 3339
date-time
. Expiration times have
the following restrictions:
- They can only be set on user and group permissions.
- Time must be in the future.
- The time cannot be more than one year in the future.
- Only the
readerrole is eligible for expiring access on a folder.
For more information about expiration date, see the following articles:

