Google Drive Permissions API

openapi: 3.2.0
info:
  title: Google Drive Permissions API
  description: The Google Drive API allows clients to access resources from Google Drive.
  version: v3
  contact:
    name: Google
    url: https://developers.google.com/workspace/drive/
  termsOfService: https://developers.google.com/terms
  x-generated-from: google-discovery
  x-source: https://www.googleapis.com/discovery/v1/apis/drive/v3/rest
  x-discovery-revision: '20261102'
  x-generated: '2026-11-04'
servers:
- url: https://www.googleapis.com/drive/v3
  description: Google Drive REST API v3
security:
- oauth2: []
tags:
- name: Permissions
paths:
  /files/{fileId}/permissions/{permissionId}:
    patch:
      operationId: updatePermission
      summary: Updates a permission with patch semantics
      description: Updates a permission with patch semantics. For more information, see Share files, folders, and drives. **Warning:** Concurrent permission modifications (such as update or delete) on the same file, folder, or shared drive aren't supported across any users or clients; only the last update is applied.
      tags:
      - Permissions
      x-discovery-id: drive.permissions.update
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the file or shared drive.
      - name: permissionId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the permission.
      - name: supportsAllDrives
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: Whether the requesting application supports both My Drives and shared drives.
      - name: transferOwnership
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: Whether to transfer ownership to the specified user and downgrade the current owner to a writer. This parameter is required as an acknowledgement of the side effect. For more information, see [Transfer file ownership](https://developers.google.com//workspace/drive/api/guides/transfer-file).
      - name: supportsTeamDrives
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Deprecated: Use `supportsAllDrives` instead.'
        deprecated: true
      - name: useDomainAdminAccess
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Issue the request as a domain administrator. If set to `true`, and if the following additional conditions are met, the requester is granted access: 1. The file ID parameter refers to a shared drive. 2. The requester is an administrator of the domain to which the shared drive belongs. For more information, see [Manage shared drives as domain administrators](https://developers.google.com/workspace/drive/api/guides/manage-shareddrives#manage-administrators).'
      - name: enforceExpansiveAccess
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Deprecated: All requests use the expansive access rules.'
        deprecated: true
      - name: removeExpiration
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: Whether to remove the expiration date.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Permission'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permission'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
    delete:
      operationId: deletePermission
      summary: Deletes a permission
      description: Deletes a permission. For more information, see Share files, folders, and drives. **Warning:** Concurrent permission modifications (such as update or delete) on the same file, folder, or shared drive aren't supported across any users or clients; only the last update is applied.
      tags:
      - Permissions
      x-discovery-id: drive.permissions.delete
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the file or shared drive.
      - name: permissionId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the permission.
      - name: supportsTeamDrives
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Deprecated: Use `supportsAllDrives` instead.'
        deprecated: true
      - name: useDomainAdminAccess
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Issue the request as a domain administrator. If set to `true`, and if the following additional conditions are met, the requester is granted access: 1. The file ID parameter refers to a shared drive. 2. The requester is an administrator of the domain to which the shared drive belongs. For more information, see [Manage shared drives as domain administrators](https://developers.google.com/workspace/drive/api/guides/manage-shareddrives#manage-administrators).'
      - name: enforceExpansiveAccess
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Deprecated: All requests use the expansive access rules.'
        deprecated: true
      - name: supportsAllDrives
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: Whether the requesting application supports both My Drives and shared drives.
      responses:
        '200':
          description: Successful response
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
    get:
      operationId: getPermission
      summary: Gets a permission by ID
      description: Gets a permission by ID. For more information, see Share files, folders, and drives.
      tags:
      - Permissions
      x-discovery-id: drive.permissions.get
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the file.
      - name: permissionId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the permission.
      - name: supportsTeamDrives
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Deprecated: Use `supportsAllDrives` instead.'
        deprecated: true
      - name: supportsAllDrives
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: Whether the requesting application supports both My Drives and shared drives.
      - name: useDomainAdminAccess
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
        description: 'Issue the request as a domain administrator. If set to `true`, and if the following additional conditions are met, the requester is granted access: 1. The file ID parameter refers to a shared drive. 2. The requester is an administrator of the domain to which the shared drive belongs. For more information, see [Manage shared drives as domain administrators](https://developers.google.com/workspace/drive/api/guides/manage-shareddrives#manage-administrators).'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permission'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.meet.readonly
        - https://www.googleapis.com/auth/drive.metadata
        - https://www.googleapis.com/auth/drive.metadata.readonly
        - https://www.googleapis.com/auth/drive.photos.readonly
        - https://www.googleapis.com/auth/drive.readonly
components:
  schemas:
    ErrorResponse:
      type: object
      description: Google API error envelope (https://cloud.google.com/apis/design/errors)
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            errors:
              type: array
              items:
                type: object
                properties:
                  domain:
                    type: string
                  reason:
                    type: string
                  message:
                    type: string
                  location:
                    type: string
                  locationType:
                    type: string
    Permission:
      type: object
      description: A permission for a file. A permission grants a user, group, domain, or the world access to a file or a folder hierarchy. For more information, see [Share files, folders, and drives](https://developers.google.com/workspace/drive/api/guides/manage-sharing). By default, permission requests only return a subset of fields. Permission `kind`, `ID`, `type`, and `role` are always returned. To retrieve specific fields, see [Return specific fields](https://developers.google.com/workspace/drive/api/guides/fields-parameter). Some resource methods (such as `permissions.update`) require a `permissionId`. Use the `permissions.list` method to retrieve the ID for a file, folder, or shared drive.
      properties:
        role:
          type: string
          description: 'The role granted by this permission. Supported values include: * `owner` * `organizer` * `fileOrganizer` * `writer` * `commenter` * `reader` For more information, see [Roles and permissions](https://developers.google.com/workspace/drive/api/guides/ref-roles).'
        domain:
          type: string
          description: Output only. The domain to which this permission refers.
          readOnly: true
        deleted:
          type: boolean
          description: Output only. Whether the account associated with this permission has been deleted. This field only pertains to permissions of type `user` or `group`.
        inheritedPermissionsDisabled:
          type: boolean
          description: When `true`, only organizers, owners, and users with permissions added directly on the item can access it.
        teamDrivePermissionDetails:
          type: array
          description: 'Output only. Deprecated: Output only. Use `permissionDetails` instead.'
          readOnly: true
          items:
            type: object
            properties:
              teamDrivePermissionType:
                type: string
                description: 'Deprecated: Output only. Use `permissionDetails/permissionType` instead.'
              inheritedFrom:
                type: string
                description: 'Deprecated: Output only. Use `permissionDetails/inheritedFrom` instead.'
              role:
                type: string
                description: 'Deprecated: Output only. Use `permissionDetails/role` instead.'
              inherited:
                type: boolean
                description: 'Deprecated: Output only. Use `permissionDetails/inherited` instead.'
        pendingOwner:
          type: boolean
          description: Whether the account associated with this permission is a pending owner. Only populated for permissions of type `user` for files that aren't in a shared drive.
        emailAddress:
          type: string
          description: Output only. The email address of the user or group to which this permission refers.
          readOnly: true
        id:
          type: string
          description: Output only. The ID of this permission. This is a unique identifier for the grantee, and is published in the [User resource](https://developers.google.com/workspace/drive/api/reference/rest/v3/User) as `permissionId`. IDs should be treated as opaque values.
        type:
          type: string
          description: 'The type of the grantee. Supported values include: * `user` * `group` * `domain` * `anyone` When creating a permission, if `type` is `user` or `group`, you must provide an `emailAddress` for the user or group. If `type` is `domain`, you must provide a `domain`. If `type` is `anyone`, no extra information is required.'
        view:
          type: string
          description: 'Indicates the view for this permission. Only populated for permissions that belong to a view. The only supported values are `published` and `metadata`: * `published`: The permission''s role is `publishedReader`. * `metadata`: The item is only visible to the `metadata` view because the item has limited access and the scope has at least read access to the parent. The `metadata` view is only supported on folders. For more information, see [Views](https://developers.google.com/workspace/drive/api/guides/ref-roles#views).'
        displayName:
          type: string
          description: 'Output only. The "pretty" name of the value of the permission. The following is a list of examples for each type of permission: * `user` - User''s full name, as defined for their Google Account, such as "Dana A." * `group` - Name of the Google Group, such as "The Company Administrators." * `domain` - String domain name, such as "cymbalgroup.com." * `anyone` - No `displayName` is present.'
        photoLink:
          type: string
          description: Output only. A link to the user's profile photo, if available.
        permissionDetails:
          type: array
          description: Output only. Details of whether the permissions on this item are inherited or are directly on this item.
          readOnly: true
          items:
            type: object
            properties:
              inherited:
                type: boolean
                description: Output only. Whether this permission is inherited. This field is always populated. This is an output-only field.
              role:
                type: string
                description: 'Output only. The primary role for this user. Supported values include: * `owner` * `organizer` * `fileOrganizer` * `writer` * `commenter` * `reader` For more information, see [Roles and permissions](https://developers.google.com/workspace/drive/api/guides/ref-roles).'
              inheritedFrom:
                type: string
                description: Output only. The ID of the item from which this permission is inherited. This is only populated for items in shared drives.
                readOnly: true
              permissionType:
                type: string
                description: 'Output only. The permission type for this user. Supported values include: * `file` * `member`'
        kind:
          type: string
          description: 'Output only. Identifies what kind of resource this is. Value: the fixed string `"drive#permission"`.'
          default: drive#permission
        expirationTime:
          type: string
          description: 'The time at which this permission will expire (RFC 3339 date-time). Expiration times have the following restrictions: - They can only be set on user and group permissions - The time must be in the future - The time cannot be more than a year in the future'
          format: date-time
        allowFileDiscovery:
          type: boolean
          description: Whether the permission allows the file to be discovered through search. This is only applicable for permissions of type `domain` or `anyone`.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/drive.scripts: Modify your Google Apps Script scripts' behavior
            https://www.googleapis.com/auth/drive.meet.readonly: See and download your Google Drive files that were created or edited by Google Meet.
            https://www.googleapis.com/auth/drive: See, edit, create, and delete all of your Google Drive files
            https://www.googleapis.com/auth/drive.appdata: See, create, and delete its own configuration data in your Google Drive
            https://www.googleapis.com/auth/drive.file: See, edit, create, and delete only the specific Google Drive files you use with this app
            https://www.googleapis.com/auth/drive.apps.readonly: View your Google Drive apps
            https://www.googleapis.com/auth/drive.photos.readonly: View the photos, videos and albums in your Google Photos
            https://www.googleapis.com/auth/drive.readonly: See and download all your Google Drive files
            https://www.googleapis.com/auth/drive.metadata: View and manage metadata of files in your Google Drive
            https://www.googleapis.com/auth/drive.metadata.readonly: See information about your Google Drive files