Data Protection Issues

How to Update Microsoft Purview Sensitivity Labels in Office Add-ins

Amos Gikunda Sep 29, 2026 868 views

Question details

The user needs to programmatically update a document's sensitivity label via an Office add-in, but modifying custom properties fails and Microsoft Graph returns a locked error.

How to Update Microsoft Purview Sensitivity Labels Through an Office Add-in

Product: Microsoft Purview / Microsoft Graph
Device & OS: not provided
Scenario: Attempting to apply or update a Microsoft Purview sensitivity label through an Office add-in while the document is currently open by a user.
Observed behavior: Microsoft Graph returns a 423 Locked or resourceLocked error because the file is in use. Additionally, changing custom document properties only alters local metadata and fails to update the authoritative label in Microsoft Graph.

Before you start

Ensure you have backend access to Microsoft Graph API and the Microsoft Information Protection (MIP) SDK, as client-side custom property modifications cannot reliably alter authoritative sensitivity labels.

Solution 1Recommended

Use a Backend Service with Retry Logic and Exponential Backoff

Send the label assignment request to a backend service that waits for the user to close the document, bypassing the 423 Locked error.

Sensitivity labels are controlled by Microsoft Information Protection and are not ordinary metadata. Changing custom properties inside the add-in only changes local values and will not update the authoritative label returned by Microsoft Graph.

Delegate to Backend

Configure your Office add-in to send the sensitivity label update payload to your custom backend service instead of trying to write to custom properties locally.

Call assignSensitivityLabel API

From your backend service, initiate a call to the Microsoft Graph assignSensitivityLabel endpoint for the target file.

Implement Retry Logic

If the file is open, the API will return a '423 Locked' or 'resourceLocked' error. Implement an exponential backoff retry mechanism that continues to attempt the assignment.

Wait for File Closure

The backend will successfully apply the label once the user has closed the file. Allow a few moments after success for the label propagation to finalize across the tenant.

Use a Backend Service with Retry Logic and Exponential Backoff

Important: Avoid continuous rapid polling. Exponential backoff prevents rate-limiting issues from Microsoft Graph while waiting for the file lock to release.

Solution 2

Apply Labels using the MIP SDK on a Downloaded Version

Alternatively, download the locked file to your server, apply the label natively via the MIP SDK, and upload it as a new version.

Free Microsoft Office alternative

Switch to WPS Office for Lightweight and Secure Document Management

While Microsoft Purview handles complex enterprise information protection, WPS Office provides a highly compatible, free alternative for everyday document editing. It supports advanced document encryption, password protection, and seamless compatibility with Microsoft Word, Excel, and PowerPoint files.

1. Download WPS Office: Visit the official WPS website to download the installer for your operating system.
2. Install the Suite: Run the setup file and follow the on-screen instructions to complete the installation.
3. Secure Your Documents: Open your Microsoft Office files in WPS and utilize the built-in encryption tools under the 'Protect' tab to secure your data.

Completely free and lightweight Office suiteHigh compatibility with Microsoft Office document formats (DOCX, XLSX, PPTX)Built-in robust document encryption and password protectionFamiliar user interface for seamless migration without a steep learning curve

microsoft office alternative - wps office

Frequently Asked Questions

Can I update sensitivity labels by modifying custom properties in the Office add-in?

No. Sensitivity labels are securely managed by Microsoft Information Protection. Modifying custom document properties through an add-in might change local metadata or UI elements, but it will not update the authoritative label registered in Microsoft Graph.

Why does Microsoft Graph return a 423 Locked error?

The '423 Locked' or 'resourceLocked' error occurs because a user currently has the document open and actively locked for editing. Microsoft Graph prevents label modifications to ensure file integrity until the active session is closed.

How long does it take for a sensitivity label to propagate after being applied?

Label propagation times can vary depending on tenant configuration and Microsoft 365 server loads. When applying labels via backend services, it is best practice to allow a few minutes for the changes to fully propagate across the system after the file is unlocked.

Is the MIP SDK required for label updates?

The MIP SDK is highly recommended if you choose to download the file and apply the label directly to the binary. However, if you are simply invoking the assignSensitivityLabel endpoint via Microsoft Graph on the server, the SDK is not strictly required.

Microsoft Office Security Issues