permission resource type

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.

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.

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

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",
  "expirationDateTime": "string (timestamp)",
  "hasPassword": "boolean"
}

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.
expirationDateTime DateTimeOffset A format of yyyy-MM-ddTHH:mm:ssZ of DateTimeOffset indicates the expiration time of the permission. DateTime.MinValue indicates there is no expiration set for this permission. Optional.
hasPassword Boolean This indicates whether password is set for this permission, it's only showing in response. Optional and Read-only and for OneDrive Personal only.

Roles enumeration values

Value 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.
sp.owner For SharePoint and OneDrive for Business this represents the owner role.
sp.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",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

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",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

This link does not grant any additional privileges to the user.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "roles": ["read"],
  "link": {
    "scope": "existingAccess",
    "type": "view",
    "webUrl": "https://contoso.sharepoint.com/:w:/t/design/Shared%20Documents/SampleDoc.docx?d=w12345",
  },
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

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",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

Sharing invitations

Permissions sent by the invite or grant API can have additional information in the invitation facet for email addresses that don't match a known account. In such cases, the grantedTo property might not be set until the invitation link 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",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

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",
  "expirationDateTime": "0001-01-01T00:00:00Z"
}

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}