Navigating sensitivity labels: a decision matrix

Introduction

Developers who must apply or read sensitivity labels programmatically have three primary options: the Microsoft Graph API, the MIP SDK, and PowerShell via the PurviewInformationProtection module. Microsoft’s documentation addresses each option independently but does not delineate the boundaries between them, specify their inherent limitations, or clarify the cost and permission implications that should inform tool selection.

Selecting an inappropriate approach can create significant impediments: the Graph API does not operate on arbitrary file types outside of SharePoint drives, the MIP SDK lacks official Python bindings, and PowerShell is generally unsuitable for scalable production automation. This article presents a decision matrix to enable practitioners to identify the appropriate toolset prior to implementation.

The Three Surfaces — Definitions and Distinctions

The Graph API and the MIP SDK both use the MIP labeling service.

• ✓Graph API: Targets Office files in SharePoint Online and OneDrive for Business.
• ✓MIP SDK: Handles files anywhere, including Windows File Explorer and custom application pipelines.
• ✓PowerShell module: The PurviewInformationProtection module builds on the MIP SDK but is not a pipeline tool.
• ✓Windows endpoints: It adds labeling support for File Explorer, the on-premises scanner, and scripted local operations.
• ✓Requirements: It requires a Windows host and interactive or service-account authentication.

Graph API

The Graph API’s assignSensitivityLabel endpoint targets files already residing in SharePoint Online or OneDrive for Business drives. It’s the right choice for cloud-native pipelines using Managed Identity or app-registration auth with Files.ReadWrite.All — no on-premises component required.

Two constraints worth knowing upfront. This API applies sensitivity labels to files at rest. Office clients don’t apply watermarks, headers, or footers to files that contain the label information — visual markings only render when the file is opened in an Office client, not at label-application time. And the Graph API cannot label arbitrary file types, files outside SharePoint/OneDrive drives, or apply encryption that travels with the file. For any of those requirements, the MIP SDK is the right path.

On cost: effective from August 25, 2025, assignSensitivityLabel is no longer metered — no Azure subscription association or per-call billing required. Reading labels via extractSensitivityLabels has always been free.

MIP SDK

The MIP SDK exposes the labeling and protection services from Microsoft Purview to third-party applications and services, with native support for applying labels and protection to files across multiple platforms.

The key distinction from the Graph API: the SDK writes label metadata and Azure Rights Management encryption directly into the file — protection that travels with it regardless of where it moves. Use it when you need to label arbitrary file types, files outside SharePoint/OneDrive, or apply encryption that must persist outside M365.

The constraint developers hit first: the MIP SDK has no Python bindings — available language bindings are C++, .NET, and Java. Python backends require a .NET or Java sidecar, or shelling out to PowerShell. SDK-based operations carry no metered API cost.

PowerShell

The PurviewInformationProtection module — successor to the AIP unified labeling client — is the right tool for one-time or periodic bulk labeling on Windows file servers, admin-initiated relabeling, and on-premises scanner scenarios. It is not suitable for production API pipelines, non-Windows environments, or high-throughput automation.

The silent failure to watch for: if a label downgrade triggers a justification requirement and no reason is supplied, the label is not applied — the status returned is “Skipped” with the comment “Justification required.” Pipelines that don’t explicitly pass a JustificationMessage parameter will silently drop label operations whenever a downgrade policy is configured.

The Decision Matrix

Which Sensitivity Label API should I use?

Answer two quick questions to find the right API for your scenario.

1. Where is your file stored?

In Microsoft 365 (SharePoint / OneDrive) 2. Should protection stay with the file after it leaves M365?

YES

MIP SDK Embedded encryption. Protection stays with file.

NO

Graph API Cloud-native. Files in SharePoint/OneDrive.

On a local drive or network share 2. Need to run on multiple platforms (non-Windows)?

YES

MIP SDK Cross-platform applications (C++, .NET, Java).

NO

PowerShell Windows-only environments & admin scripts.

Up Next

Blog 2.2 goes deep on Container labels vs item labels — technical detail on both object models, the scope separation, the no-inheritance rule, the delegated-only constraint, and the Teams shared channel inheritance behavior.