driveItem: assignSensitivityLabel

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.

Asynchronously assign a sensitivity label to a driveItem.

This API is part of Microsoft SharePoint and OneDrive APIs that perform advanced premium administrative functions and is considered a protected API. Protected APIs require you to have more validation, beyond permission and consent, before you can use them. Before you call this API, you must request access.

For more information about sensitivity labels from an administrator's perspective, see Enable sensitivity labels for Office files in SharePoint and OneDrive.

Note

This is a metered API and some charges for use may apply. For details, see Overview of metered Microsoft 365 APIs in Microsoft Graph.

This API is supported in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	Files.ReadWrite.All, Sites.ReadWrite.All
Delegated (personal Microsoft account)	Not supported.
Application	Files.ReadWrite.All, Sites.ReadWrite.All

HTTP request

POST /drives/{drive-id}/items/{item-id}/assignSensitivityLabel
POST /drives/{drive-id}/root:/{item-path}:/assignSensitivityLabel
POST /groups/{group-id}/drive/items/{item-id}/assignSensitivityLabel
POST /groups/{group-id}/drive/root:/{item-path}:/assignSensitivityLabel
POST /me/drive/items/{item-id}/assignSensitivityLabel
POST /me/drive/root:/{item-path}:/assignSensitivityLabel
POST /sites/{site-id}/drive/items/{item-id}/assignSensitivityLabel
POST /sites/{site-id}/drive/root:/{item-path}:/assignSensitivityLabel
POST /users/{user-id}/drive/items/{item-id}/assignSensitivityLabel
POST /users/{user-id}/drive/root:/{item-path}:/assignSensitivityLabel

Request headers

Name	Description
Authorization	Bearer {token}. Required.

Request body

In the request body, provide the ID for the sensitivity label that is to be assigned to a given file. The following table lists the required and optional input parameters.

Name	Value	Description
sensitivityLabelId	String	Required. ID of the sensitivity label to be assigned, or empty string to remove the sensitivity label.
assignmentMethod	sensitivityLabelAssignmentMethod	Optional. The assignment method of the label on the document. Indicates whether the assignment of the label was done automatically, standard, or as a privileged operation (the equivalent of an administrator operation).
justificationText	String	Optional. Justification text for audit purposes. Required when downgrading or removing a label.

Response

If successful, the API returns a 202 Accepted HTTP response code with an empty response body. The Location header provides the URL to get operation details. For more information about how to monitor the progress of an assign sensitivity label operation, see monitoring long-running operations.

In addition to general errors that apply to Microsoft Graph, this API returns the 423 Locked response code, which indicates that the file being accessed is locked. In such cases, the code property of the response object indicates the error type that blocks the operation. Also, Few Irm Protected sensitivity labels can't be updated by Application and need delegated user access to validate if the user has proper rights. For these scenarios, the API throws Not Supported response code.

The following table lists the possible values for the error types.

Value	Description
fileDoubleKeyEncrypted	Indicates that the file is protected via double key encryption; therefore, it can't be opened.
fileDecryptionNotSupported	Indicates that the encrypted file has specific properties that don't allow these files to be opened by SharePoint.
fileDecryptionDeferred	Indicates that the file is being processed for decryption; therefore, it can't be opened.
unknownFutureValue	Evolvable enumeration sentinel value. Don't use.

Examples

Request

Here's an example of a request.

HTTP

POST https://graph.microsoft.com/beta/drive/root/items/016GVDAP3RCQS5VBQHORFIVU2ZMOSBL25U/assignSensitivityLabel
Content-Type: application/json

{
  "sensitivityLabelId": "5feba255-812e-446a-ac59-a7044ef827b5",
  "assignmentMethod": "standard",
  "justificationText": "test_justification"
}

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const assignSensitivityLabel = {
  sensitivityLabelId: '5feba255-812e-446a-ac59-a7044ef827b5',
  assignmentMethod: 'standard',
  justificationText: 'test_justification'
};

await client.api('/drive/root/items/016GVDAP3RCQS5VBQHORFIVU2ZMOSBL25U/assignSensitivityLabel')
	.version('beta')
	.post(assignSensitivityLabel);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/QXNzaWduU2Vuc2l0aXZpdHlMYWJlbCxiMzc3ODY3OS04OWQ3LTRkYmYtYjg0MC1jYWM1NzRhY2FlNmE?tempAuth=eyJ0eXAiOiJKV1QiLCJhb....

The value of the Location header provides a URL for a service that will return the current state of the assign sensitivity label operation. You can use this information to determine when the assign sensitivity label operation has finished.

Remarks

The response from the API only indicates that the assign sensitivity label operation was accepted or rejected. The operation might be rejected, for example, if the file type isn't supported, or the file is double encrypted.