Manage pending access proposals

An access proposal is a proposal from a requester to an approver to grant a recipient access to a Google Drive item.

An approver can review and act on all unresolved access proposals across Drive files. This means you can speed up the approval process by programmatically querying for access proposals and then resolving them. It also allows proposals to be viewed in aggregate by an approver.

The Google Drive API provides the accessproposals resource so you can view and resolve pending access proposals. The methods of the accessproposals resource work on files, folders, the files within a shared drive but not on the shared drive.

The following terms are specific to access proposals:

  • Requester: The user initiating the access proposal to a Drive item.
  • Recipient: The user receiving the additional permissions on a file if the access proposal is granted. Many times the recipient is the same as the requester but not always.
  • Approver: The user responsible for approving (or denying) the access proposal. This is typically because they're an owner on the document or they have the ability to share the document.

List pending access proposals

To list all pending access proposals on a Drive item, call the list() method on the accessproposals resource and include the fileId path parameter.

Only approvers on a file can list the pending proposals on a file. An approver is a user with the can_approve_access_proposals capability on the file. If the requester isn't an approver, an empty list is returned. For more information about capabilities, see Understand file capabilities.

The response body consists of an AccessProposal object representing a list of unresolved access proposals on the file.

The AccessProposal object includes info about each proposal such as the requester, the recipient, and the message that the requester added. It also includes an AccessProposalRoleAndView object that groups the requester's proposed role with a view. Since role is a repeated field, multiples could exist for each proposal. For example, a proposal might have an AccessProposalRoleAndView object of role=reader and view=published, plus an additional AccessProposalRoleAndView object with only the role=writer value. For more information, see Views.

Pass the following query parameters to customize pagination of, or filter, access proposals:

  • pageToken: A page token, received from a previous list call. Provide this token to retrieve the subsequent page.

  • pageSize: The maximum number of access proposals to return per page.

Resolve pending access proposals

To resolve all pending access proposals on a Drive item, call the resolve() method on the accessproposals resource and include the fileId and proposalId path parameters.

The resolve() method includes an action query parameter that denotes the action to take on the proposal. The Action object tracks the state change of the proposal so we know if it's being accepted or denied.

The resolve() method also includes the optional query parameters of role and view. The only supported roles are writer, commenter, and reader. If the role isn't specified, it defaults to reader. An additional optional query parameter of send_notification lets you send an email notification to the requester when the proposal is accepted or denied.

Just as with the list() method, users resolving the proposal must have the can_approve_access_proposals capability on the file. For more information about capabilities, see Understand file capabilities.

Proposals are resolved using the same patterns listed under Scenarios for sharing Drive resources. If there are multiple proposals for the same user, but with different roles, the following applies:

  • If one proposal is accepted and one is denied, the accepted role applies to the Drive item.
  • If both proposals are accepted at the same time, the proposal with the higher permission (for example, role=writer versus role=reader) is applied. The other access proposal is removed from the item.

After sending a proposal to the resolve() method, the sharing action is complete. The AccessProposal is no longer returned through the list() method. Once the proposal is accepted, the user must use the permissions collection to update permissions on a file or folder. For more information, see Update permissions.