Edit

Share via

permission resource type

  • Article

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

The permission resource provides information about a sharing permission granted for a driveItem resource.

Sharing permissions have many 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.

OneDrive for Business and SharePoint document libraries don't return the inheritedFrom property. grantedTo and grantedToIdentities will be deprecated going forward and the response will be migrated to grantedToV2 and grantedToIdentitiesV2 respectively under appropriate property names.

JSON representation

The following JSON representation shows the resource type.

{
  "id": "string (identifier)",
  "grantedTo": {"@odata.type": "microsoft.graph.identitySet"},
  "grantedToIdentities": [{"@odata.type": "microsoft.graph.identitySet"}],
  "grantedToV2": {"@odata.type": "microsoft.graph.sharePointIdentitySet"},
  "grantedToIdentitiesV2": [{"@odata.type": "microsoft.graph.sharePointIdentitySet"}],
  "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.
grantedToV2 SharePointIdentitySet For user type permissions, the details of the users and applications for this permission. Read-only.
grantedToIdentitiesV2 Collection(SharePointIdentitySet) 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's inherited from an ancestor. Read-only.
link SharingLink Provides the link details of the current permission, if it's a link type permission. Read-only.
roles Collection(String) The type of permission, for example, read. See the Roles property values section 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's no expiration set for this permission. Optional.
hasPassword Boolean Indicates whether the password is set for this permission. This property only appears in the response. Optional. Read-only. For OneDrive Personal only.
grantedTo (deprecated) IdentitySet For user type permissions, the details of the users and applications for this permission. Read-only.
grantedToIdentities (deprecated) Collection(IdentitySet) For type permissions, the details of the users to whom permission was granted. Read-only.

Roles property values

Value Description
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.

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 various 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 doesn't 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"
      }
    }
  ],
  "grantedToIdentitiesV2": [
    {
       "user": {
        "id": "35fij1974gb8832",
        "displayName": "Misty Suarez"
      },
      "siteUser": {
        "id": "1",
        "displayName": "Misty Suarez",
        "loginName": "Misty Suarez"
      }
    },
    {
       "user": {
        "id": "9397721fh4hgh73",
        "displayName": "Judith Clemons"
      },
      "siteUser": {
        "id": "2",
        "displayName": "Judith Clemons",
        "loginName": "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": "Robin Danielsen"
    }
  },
  "grantedToV2": {
    "user": {
      "id": "5D33DD65C6932946",
      "displayName": "Robin Danielsen"
    },
    "siteUser": {
      "id": "1",
      "displayName": "Robin Danielsen",
      "loginName": "Robin Danielsen"
    }
  },
  "invitation": {
    "email": "rd@contoso.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 permission PATCH /drive/items/{item-id}/permissions/{id}
Delete permission DELETE /drive/items/{item-id}/permissions/{id}
Grant access to sharing link POST /shares/{encoded-sharing-url}/permission/grant
Revoke grants on sharing link POST /drive/items/{item-id}/permissions/{id}/revokeGrants