Edit

Permission resource type

  • Article

The Permission resource provides information about a sharing permission granted for a DriveItem resource.

Sharing permissions have a number of different forms. The Permission resource represents these different forms through facets on the resource.

JSON representation

Here is a JSON representation of the resource

{
  "id": "string (identifier)",
  "grantedTo": {"@odata.type": "microsoft.graph.identitySet"},
  "grantedToIdentities": [{"@odata.type": "microsoft.graph.identitySet"}],
  "inheritedFrom": {"@odata.type": "microsoft.graph.itemReference"},
  "invitation": {"@odata.type": "microsoft.graph.sharingInvitation"},
  "link": {"@odata.type": "microsoft.graph.sharingLink"},
  "roles": ["string"],
  "shareId": "string"
}

Properties

Property Type Description
id String The unique identifier of the permission among all permissions on the item. Read-only.
grantedTo IdentitySet For user type permissions, the details of the users & applications for this permission. Read-only.
grantedToIdentities Collection(IdentitySet) For link type permissions, the details of the users to whom permission was granted. Read-only.
invitation SharingInvitation Details of any associated sharing invitation for this permission. Read-only.
inheritedFrom ItemReference Provides a reference to the ancestor of the current permission, if it is inherited from an ancestor. Read-only.
link SharingLink Provides the link details of the current permission, if it is a link type permissions. Read-only.
roles Collection(String) The type of permission, e.g. read. See below for the full list of roles. Read-only.
shareId String A unique token that can be used to access this shared item via the shares API. Read-only.

Roles enumeration

Role Details
read Provides the ability to read the metadata and contents of the item.
write Provides the ability to read and modify the metadata and contents of the item.
owner For SharePoint and OneDrive for Business this represents the owner role.
member For SharePoint and OneDrive for Business this represents the member role.

The permission resource uses facets to provide information about the kind of permission represented by the resource.

Sharing links contain a unique token required to access the item.

Permissions with an invitation facet represent permissions added by inviting specific users or groups to have access to the file.

Permissions with a link facet represent sharing links created on the item. These are the most common kinds of permissions. Sharing links provide a unique URL that can be used to access a file or folder. They can be set up to grant access in a variety of ways. For example, you can use the createLink API to create a link that works for anyone signed into your organization, or you can create a link that works for anyone, without needing to sign in. You can use the invite API to create a link that only works for specific people, whether they're in your company or not.

Here are some examples of sharing links.

This view link provides read-only access to anyone with the link.

{
  "id": "1",
  "roles": ["read"],
  "link": {
    "scope": "anonymous",
    "type": "view",
    "webUrl": "https://onedrive.live.com/redir?resid=5D33DD65C6932946!70859&authkey=!AL7N1QAfSWcjNU8&ithint=folder%2cgif",
    "application": { "id": "1234", "displayName": "Sample Application" }
  },
  "shareId": "!LKj1lkdlals90j1nlkascl"
}

This edit link provides read and write access to anyone in the organization with the link.

{
  "id": "2ceefb3g32hh",
  "roles": ["write"],
  "link": {
    "scope": "organization",
    "type": "edit",
    "webUrl": "https://contoso.sharepoint.com/:w:/t/design/fj277ghautbb422707565gnvg23",
    "application": { "id": "1234", "displayName": "Sample Application" }
  },
  "shareId": "!LKj1lkdlals90j1nlkascl"
}

This link provides read and write access to the specific people in the grantedToIdentities collection.

{
  "id": "3",
  "grantedToIdentities": [
    {
       "user": {
        "id": "35fij1974gb8832",
        "displayName": "Misty Suarez"
      }
    },
    {
       "user": {
        "id": "9397721fh4hgh73",
        "displayName": "Judith Clemons"
      }
    }
  ],
  "roles": ["write"],
  "link": {
    "webUrl": "https://contoso.sharepoint.com/:w:/t/design/a577ghg9hgh737613bmbjf839026561fmzhsr85ng9f3hjck2t5s",
    "application": { "id": "1234", "displayName": "Sample Application" }
  },
  "shareId": "!LKj1lkdlals90j1nlkascl"
}

Sharing Invitations

Permissions sent by the invite API may have additional information in the invitation facet. If an invitation was sent to an email address that doesn't match a known account, the grantedTo property may not be set until the invitation is redeemed, which occurs the first time the user clicks the link and signs in.

{
  "id": "1",
  "roles": ["write"],
  "invitation": {
    "email": "jd@fabrikam.com",
    "signInRequired": true
  },
  "shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U"
}

After the sharing invitation has been redeemed by a user, the grantedTo property will contain the information about the account that redeemed the permissions:

{
  "id": "1",
  "roles": ["write"],
  "grantedTo": {
    "user": {
      "id": "5D33DD65C6932946",
      "displayName": "John Doe"
    }
  },
  "invitation": {
    "email": "jd@fabrikam.com",
    "signInRequired": true
  },
  "shareId": "FWxc1lasfdbEAGM5fI7B67aB5ZMPDMmQ11U"
}

Methods

Method REST Path
List permissions GET /drive/items/{item-id}/permissions
Get permission GET /drive/items/{item-id}/permissions/{id}
Create link POST /drive/items/{item-id}/createLink
Invite people POST /drive/items/{item-id}/invite
Update PATCH /drive/items/{item-id}/permissions/{id}
Delete DELETE /drive/items/{item-id}/permissions/{id}

Remarks

OneDrive for Business and SharePoint document libraries do not return the inheritedFrom property.