Skip to content

driveitem-post-permissions.md

Latest commit

 

History

History
260 lines (206 loc) · 9.76 KB

driveitem-post-permissions.md

File metadata and controls

260 lines (206 loc) · 9.76 KB
title Create permission on a driveItem
description Create a new permission object for a driveItem.
author BarrySh
ms.localizationpriority medium
ms.subservice sharepoint
doc_type apiPageType
ms.date 11/21/2025

Create permission on a driveItem

Namespace: microsoft.graph

[!INCLUDE beta-disclaimer]

Create a new permission object on a driveItem.

Important

This API has the following restrictions:

  • For OneDrive for work or school and SharePoint Online, you can only use this method to create a new application permission. If you want to create a new user permission in a driveItem, see invite. For more information on application permissions, see Overview of Selected permissions in OneDrive and SharePoint.
  • For SharePoint Embedded, you can only use this method to create a new sharePointGroup permission with app-only access. You can't create a permission on the root item of a container.

[!INCLUDE national-cloud-support]

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

[!INCLUDE permissions-table]

[!INCLUDE app-permissions]

HTTP request

POST /drives/{drive-id}/items/{item-id}/permissions
POST /groups/{group-id}/drive/items/{item-id}/permissions
POST /me/drive/items/{item-id}/permissions
POST /sites/{siteId}/drive/items/{itemId}/permissions
POST /users/{userId}/drive/items/{itemId}/permissions

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, supply a JSON representation of the permission object.

Important

  • This API only accepts grantedToV2 as input for the permission object. Other properties such as grantedToIdentitiesV2 or the deprecated grantedTo and grantedToIdentities are not accepted.
  • For SharePoint Embedded, when creating a new sharePointGroup permission, the request body must include both the id and displayName of the sharePointGroup referenced in the grantedToV2.siteGroup property. See Example 2.

Response

If successful, this method returns a 201 Created response code and a permission object in the response body.

Examples

Example 1: Add an application permission to a driveItem in OneDrive or SharePoint Online

The following example shows how to add a write permission for the Contoso Time Manager App application identified by 89ea5c94-7736-4e25-95ad-3fa95f62b66e, on a driveItem identified by 01V4EPHZNV2OJQJNBPWNCKDTXCQ5TSVBJU in a drive identified by b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop.

Request

The following example shows a request.

HTTP

POST https://graph.microsoft.com/beta/drives/b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop/items/01V4EPHZNV2OJQJNBPWNCKDTXCQ5TSVBJU/permissions
Content-Type: application/json

{
  "grantedToV2": {
    "application": {
      "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e"
    }
  },
  "roles": ["write"]
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "aTowaS50fG1zLnNwLmV4dHw4OWVhNWM5NC03NzM2LTRlMjUtOTVhZC0zZmE5NWY2MmI2NmVAZDljZTBmYzEtNjFkOC00YTJlLWI1ZDMtMTg3NzBkZjA2NzJj",
  "roles": [
    "write"
  ],
  "grantedTo": {
    "application": {
      "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
      "displayName": "Contoso Time Manager App"
    }
  },
  "grantedToV2": {
    "application": {
      "id": "89ea5c94-7736-4e25-95ad-3fa95f62b66e",
      "displayName": "Contoso Time Manager App"
    }
  }
}

Example 2: Add a SharePoint group permission to a driveItem in a SharePoint Embedded container

The following example shows how to add a write permission for the Internal Collaborators sharePointGroup on a driveItem identified by 01V4EPHZNV2OJQJNBPWNCKDTXCQ5TSVBJU in a SharePoint Embedded fileStorageContainer identified by b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop.

Request

The following example shows a request.

HTTP

POST https://graph.microsoft.com/beta/drives/b!s8RqPCGh0ESQS2EYnKM0IKS3lM7GxjdAviiob7oc5pXv_0LiL-62Qq3IXyrXnEop/items/01V4EPHZNV2OJQJNBPWNCKDTXCQ5TSVBJU/permissions
Content-Type: application/json

{
  "grantedToV2": {
    "siteGroup": {
      "id": "10",
      "displayName": "Internal Collaborators"
    }
  },
  "roles": ["write"]
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "aTowaS50fG1zLnNwLmV4dHwxMEBkOWNlMGZjMS02MWQ4LTRhMmUtYjVkMy0xODc3MGRmMDY3MmM=",
  "roles": [
    "write"
  ],
  "grantedToV2": {
    "siteGroup": {
      "id": "10",
      "displayName": "Internal Collaborators"
    }
  },
  "grantedTo": {
    "siteGroup": {
      "id": "10",
      "displayName": "Internal Collaborators"
    }
  }
}