Microsoft 365 Shares.permission API

openapi: 3.2.0
info:
  title: Files Shares.permission API
  version: v1.0
servers:
- url: https://graph.microsoft.com/v1.0/
  description: Core
security:
- azureaadv2: []
tags:
- name: shares.permission
paths:
  /shares/{sharedDriveItem-id}/permission:
    get:
      tags:
      - shares.permission
      summary: Get permission from shares
      description: Used to access the permission representing the underlying sharing link
      operationId: share_GetPermission
      parameters:
      - name: sharedDriveItem-id
        in: path
        description: The unique identifier of sharedDriveItem
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: sharedDriveItem
      - name: $select
        in: query
        description: Select properties to be returned
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: $expand
        in: query
        description: Expand related entities
        style: form
        explode: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        2XX:
          description: Retrieved navigation property
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.permission'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    patch:
      tags:
      - shares.permission
      summary: Update the navigation property permission in shares
      operationId: share_UpdatePermission
      parameters:
      - name: sharedDriveItem-id
        in: path
        description: The unique identifier of sharedDriveItem
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: sharedDriveItem
      requestBody:
        description: New navigation property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/microsoft.graph.permission'
        required: true
      responses:
        2XX:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/microsoft.graph.permission'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
      - shares.permission
      summary: Delete navigation property permission for shares
      operationId: share_DeletePermission
      parameters:
      - name: sharedDriveItem-id
        in: path
        description: The unique identifier of sharedDriveItem
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: sharedDriveItem
      - name: If-Match
        in: header
        description: ETag
        style: simple
        schema:
          type: string
      responses:
        2XX:
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /shares/{sharedDriveItem-id}/permission/microsoft.graph.grant:
    post:
      tags:
      - shares.permission
      summary: Invoke action grant
      description: Grant users access to a link represented by a permission.
      externalDocs:
        description: Find more info here
        url: https://learn.microsoft.com/graph/api/permission-grant?view=graph-rest-1.0
      operationId: share.permission_grant
      parameters:
      - name: sharedDriveItem-id
        in: path
        description: The unique identifier of sharedDriveItem
        required: true
        style: simple
        schema:
          type: string
        x-ms-docs-key-type: sharedDriveItem
      requestBody:
        description: Action parameters
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  type: array
                  items:
                    type:
                    - string
                    - 'null'
                recipients:
                  type: array
                  items:
                    $ref: '#/components/schemas/microsoft.graph.driveRecipient'
              additionalProperties:
                type: object
        required: true
      responses:
        2XX:
          description: Success
          content:
            application/json:
              schema:
                title: Collection of permission
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/microsoft.graph.permission'
                  '@odata.nextLink':
                    type:
                    - string
                    - 'null'
                additionalProperties:
                  type: object
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: action
      x-ms-pageable:
        nextLinkName: '@odata.nextLink'
        operationName: listMore
components:
  schemas:
    microsoft.graph.ODataErrors.InnerError:
      type: object
      additionalProperties:
        type: object
      description: The structure of this object is service-specific
    microsoft.graph.itemReference:
      title: itemReference
      type: object
      properties:
        driveId:
          type:
          - string
          - 'null'
          description: Unique identifier of the drive instance that contains the driveItem. Only returned if the item is located in a drive. Read-only.
        driveType:
          type:
          - string
          - 'null'
          description: Identifies the type of drive. Only returned if the item is located in a drive. See drive resource for values.
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the driveItem in the drive or a listItem in a list. Read-only.
        name:
          type:
          - string
          - 'null'
          description: The name of the item being referenced. Read-only.
        path:
          type:
          - string
          - 'null'
          description: Percent-encoded path that can be used to navigate to the item. Read-only.
        shareId:
          type:
          - string
          - 'null'
          description: A unique identifier for a shared resource that can be accessed via the Shares API.
        sharepointIds:
          $ref: '#/components/schemas/microsoft.graph.sharepointIds'
        siteId:
          type:
          - string
          - 'null'
          description: For OneDrive for Business and SharePoint, this property represents the ID of the site that contains the parent document library of the driveItem resource or the parent list of the listItem resource. The value is the same as the id property of that site resource. It is an opaque string that consists of three identifiers of the site. For OneDrive, this property is not populated.
      additionalProperties:
        type: object
    microsoft.graph.identitySet:
      title: identitySet
      type: object
      properties:
        application:
          $ref: '#/components/schemas/microsoft.graph.identity'
        device:
          $ref: '#/components/schemas/microsoft.graph.identity'
        user:
          $ref: '#/components/schemas/microsoft.graph.identity'
      additionalProperties:
        type: object
    microsoft.graph.sharePointGroupIdentity:
      allOf:
      - $ref: '#/components/schemas/microsoft.graph.identity'
      - title: sharePointGroupIdentity
        type: object
        properties:
          principalId:
            type:
            - string
            - 'null'
            description: The principal ID of the SharePoint group in the tenant. Read-only.
          title:
            type:
            - string
            - 'null'
            description: The title of the SharePoint group. Read-only.
        additionalProperties:
          type: object
    microsoft.graph.ODataErrors.ErrorDetails:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type:
          - string
          - 'null'
      additionalProperties:
        type: object
    microsoft.graph.ODataErrors.MainError:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
          x-ms-primary-error-message: true
        target:
          type:
          - string
          - 'null'
        details:
          type: array
          items:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ErrorDetails'
        innerError:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.InnerError'
      additionalProperties:
        type: object
    microsoft.graph.permission:
      allOf:
      - $ref: '#/components/schemas/microsoft.graph.entity'
      - title: permission
        type: object
        properties:
          expirationDateTime:
            pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$
            type:
            - string
            - 'null'
            description: A format of yyyy-MM-ddTHH:mm:ssZ of DateTimeOffset indicates the expiration time of the permission. DateTime.MinValue indicates there's no expiration set for this permission. Optional.
            format: date-time
          grantedTo:
            $ref: '#/components/schemas/microsoft.graph.identitySet'
          grantedToIdentities:
            type: array
            items:
              $ref: '#/components/schemas/microsoft.graph.identitySet'
            description: For type permissions, the details of the users to whom permission was granted. Read-only.
          grantedToIdentitiesV2:
            type: array
            items:
              $ref: '#/components/schemas/microsoft.graph.sharePointIdentitySet'
            description: For link type permissions, the details of the users to whom permission was granted. Read-only.
          grantedToV2:
            $ref: '#/components/schemas/microsoft.graph.sharePointIdentitySet'
          hasPassword:
            type:
            - boolean
            - 'null'
            description: Indicates whether the password is set for this permission. This property only appears in the response. Optional. Read-only. For OneDrive Personal only..
          inheritedFrom:
            $ref: '#/components/schemas/microsoft.graph.itemReference'
          invitation:
            $ref: '#/components/schemas/microsoft.graph.sharingInvitation'
          link:
            $ref: '#/components/schemas/microsoft.graph.sharingLink'
          roles:
            type: array
            items:
              type:
              - string
              - 'null'
            description: The type of permission, for example, read. See below for the full list of roles. Read-only.
          shareId:
            type:
            - string
            - 'null'
            description: A unique token that can be used to access this shared item via the shares API. Read-only.
        additionalProperties:
          type: object
    microsoft.graph.ODataErrors.ODataError:
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/microsoft.graph.ODataErrors.MainError'
      additionalProperties:
        type: object
    microsoft.graph.sharePointIdentitySet:
      allOf:
      - $ref: '#/components/schemas/microsoft.graph.identitySet'
      - title: sharePointIdentitySet
        type: object
        properties:
          group:
            $ref: '#/components/schemas/microsoft.graph.identity'
          sharePointGroup:
            $ref: '#/components/schemas/microsoft.graph.sharePointGroupIdentity'
          siteGroup:
            $ref: '#/components/schemas/microsoft.graph.sharePointIdentity'
          siteUser:
            $ref: '#/components/schemas/microsoft.graph.sharePointIdentity'
        additionalProperties:
          type: object
    microsoft.graph.sharepointIds:
      title: sharepointIds
      type: object
      properties:
        listId:
          type:
          - string
          - 'null'
          description: The unique identifier (guid) for the item's list in SharePoint.
        listItemId:
          type:
          - string
          - 'null'
          description: An integer identifier for the item within the containing list.
        listItemUniqueId:
          type:
          - string
          - 'null'
          description: The unique identifier (guid) for the item within OneDrive for Business or a SharePoint site.
        siteId:
          type:
          - string
          - 'null'
          description: The unique identifier (guid) for the item's site collection (SPSite).
        siteUrl:
          type:
          - string
          - 'null'
          description: The SharePoint URL for the site that contains the item.
        tenantId:
          type:
          - string
          - 'null'
          description: The unique identifier (guid) for the tenancy.
        webId:
          type:
          - string
          - 'null'
          description: The unique identifier (guid) for the item's site (SPWeb).
      additionalProperties:
        type: object
    microsoft.graph.sharePointIdentity:
      allOf:
      - $ref: '#/components/schemas/microsoft.graph.identity'
      - title: sharePointIdentity
        type: object
        properties:
          loginName:
            type:
            - string
            - 'null'
            description: The sign in name of the SharePoint identity.
        additionalProperties:
          type: object
    microsoft.graph.driveRecipient:
      title: driveRecipient
      type: object
      properties:
        alias:
          type:
          - string
          - 'null'
          description: The alias of the domain object, for cases where an email address is unavailable (for example, security groups).
        email:
          type:
          - string
          - 'null'
          description: The email address for the recipient, if the recipient has an associated email address.
        objectId:
          type:
          - string
          - 'null'
          description: The unique identifier for the recipient in the directory.
      additionalProperties:
        type: object
    microsoft.graph.sharingLink:
      title: sharingLink
      type: object
      properties:
        application:
          $ref: '#/components/schemas/microsoft.graph.identity'
        preventsDownload:
          type:
          - boolean
          - 'null'
          description: If true then the user can only use this link to view the item on the web, and cannot use it to download the contents of the item. Only for OneDrive for Business and SharePoint.
        scope:
          type:
          - string
          - 'null'
          description: The scope of the link represented by this permission. Value anonymous indicates the link is usable by anyone, organization indicates the link is only usable for users signed into the same tenant.
        type:
          type:
          - string
          - 'null'
          description: The type of the link created.
        webHtml:
          type:
          - string
          - 'null'
          description: For embed links, this property contains the HTML code for an <iframe> element that will embed the item in a webpage.
        webUrl:
          type:
          - string
          - 'null'
          description: A URL that opens the item in the browser on the OneDrive website.
      additionalProperties:
        type: object
    microsoft.graph.entity:
      title: entity
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for an entity. Read-only.
      additionalProperties:
        type: object
    microsoft.graph.identity:
      title: identity
      type: object
      properties:
        displayName:
          type:
          - string
          - 'null'
          description: The display name of the identity.For drive items, the display name might not always be available or up to date. For example, if a user changes their display name the API might show the new value in a future response, but the items associated with the user don't show up as changed when using delta.
        id:
          type:
          - string
          - 'null'
          description: Unique identifier for the identity or actor. For example, in the access reviews decisions API, this property might record the id of the principal, that is, the group, user, or application that's subject to review.
      additionalProperties:
        type: object
    microsoft.graph.sharingInvitation:
      title: sharingInvitation
      type: object
      properties:
        email:
          type:
          - string
          - 'null'
          description: The email address provided for the recipient of the sharing invitation. Read-only.
        invitedBy:
          $ref: '#/components/schemas/microsoft.graph.identitySet'
        redeemedBy:
          type:
          - string
          - 'null'
        signInRequired:
          type:
          - boolean
          - 'null'
          description: If true the recipient of the invitation needs to sign in in order to access the shared item. Read-only.
      additionalProperties:
        type: object
  responses:
    error:
      description: error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/microsoft.graph.ODataErrors.ODataError'
  securitySchemes:
    azureaadv2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes: {}