MS OneDrive – Add Library Item Permissions

Grants access to the specified recipients and optionally sends invitation emails. Recipients and Roles are comma-separated strings converted to Graph recipients and roles arrays. Supply read or write roles and choose Require Sign In and Send Invitation explicitly. Expiration Date Time, Password, and Retain Inherited Permissions are sent only when populated. App-only access can invite existing guests but cannot invite new guests; password is supported only for OneDrive personal. Microsoft can return partial success for multiple recipients. The current permission model does not expose recipient error objects; inspect the actual grants rather than assuming every invitation succeeded.

Action details

Property	Value
Action label	MS OneDrive – Add Library Item Permissions
Category	CloudTools
Apex class and method	AddOneDriveLibraryItemPermissions.addPermissions
Input type	AddOneDriveLibraryItemPermissions.AddOneDriveLibraryItemPermissionsInput
Output type	List<MSGraphDrivePermission>
Authorization	OAuth Delegated (Authorization Code) or OAuth Application (Client Credentials).
Flow automation	Use an application connector configured as the Flow default.
Microsoft Graph operation	POST /v1.0/drives/{driveId}/items/{itemId}/invite for Authorization Code Flow; otherwise POST /v1.0/users/{userIdOrPrincipalName}/drives/{driveId}/items/{itemId}/invite.

Prerequisites and permissions

Configure a CloudTools Connector with Connector Type set to Microsoft 365. For delegated access, complete the current user’s Microsoft sign-in. For application access where supported, grant application permissions and administrator consent and provide the target user ID or principal name. The identity must have access to the selected drive and item.

Delegated calls require Files.ReadWrite or a supported broader write permission; application calls require Files.ReadWrite.All or Sites.ReadWrite.All. See the Microsoft operation and permissions reference.

Drive selection: For Authorization Code Flow, a populated driveId uses /drives/{driveId} and userIdOrPrincipalName is ignored. Other authorization types require userIdOrPrincipalName and use the user-scoped drive path shown above. A Library Id is a Graph drive ID and Item Id is an item within that drive; neither is a Salesforce record ID or browser URL.

Inputs

The table lists action labels, Apex field names, and Apex data types. Supply one non-null request with nonblank required text values.

Input	Apex field	Type	Required	Description
User Id or Principal Name	userIdOrPrincipalName	String	Unless Authorization Code Flow is enabled	User id or user principal name. Ignored for Authorization Code Flow.
Library Id	driveId	String	Yes	Library (drive) identifier.
Item Id	itemId	String	Yes	Library (drive) item identifier.
Recipients	recipients	String	Yes	Comma-separated recipient email addresses.
Roles	roles	String	Yes	Comma-separated roles (read, write).
Message	message	String	No	Invitation message.
Require Sign In	requireSignIn	Boolean	No	Require recipients to sign in.
Send Invitation	sendInvitation	Boolean	No	Send invitation email.
Expiration Date Time	expirationDateTime	String	No	ISO 8601 expiration timestamp.
Password	password	String	No	Password for the invitation.
Retain Inherited Permissions	retainInheritedPermissions	Boolean	No	Keep inherited permissions when sharing for the first time.

The global invocable input has no connectorId field. Direct subscriber Apex and Flow calls use CloudTools connector selection. This action does not resolve replacement tokens; resolve dynamic values before invocation. See Using Token Replacements.

Outputs

Returns a flat List<MSGraphDrivePermission> of matching results for the first request, or an empty list if no results are mapped. These entries are resource results, not one response per input request.

Output	Apex field	Type	Description
id	id	String	Microsoft Graph resource identifier.
roles	roles	List<String>	Granted roles, such as read or write.
inheritedFrom	inheritedFrom	MSGraphDriveItemReference	Parent reference from which a permission is inherited.
grantedTo	grantedTo	MSGraphDriveIdentitySet	Original granted identity set.
grantedToV2	grantedToV2	MSGraphDriveIdentitySet	Granted identity set in the newer Graph shape.

Mapping limitation: MSGraphDrivePermission exposes only id, roles, inheritedFrom, grantedTo, and grantedToV2. It has no link, invitation, expirationDateTime, recipient-error, or rawJson field. In particular, Create Sharing Link can succeed without returning its link URL through this model. The LWC controller attempts to derive linkType, linkScope, linkWebUrl, and expirationDateTime from the mapped object, so those fields remain unavailable with the current model. Its rawJson serializes the mapped object and does not recover omitted Microsoft fields.

Use in Flow

Add MS OneDrive – Add Library Item Permissions in Flow Builder. Use a Microsoft 365 application connector configured as Set as default for Flow automations, supply the target user and resource IDs, and handle faults. Delegated connections are not supported for CloudTools Flow automation. This implementation processes only the first request; it is not a bulk operation.

Use in custom Apex

This subscriber-org example uses the Apptigent namespace. Replace all identifiers and run in a context that permits callouts with a configured connector. The example supplies the user for application access; omit it for an already-authorized delegated connector.

Apptigent.AddOneDriveLibraryItemPermissions.AddOneDriveLibraryItemPermissionsInput request =
    new Apptigent.AddOneDriveLibraryItemPermissions.AddOneDriveLibraryItemPermissionsInput();
request.userIdOrPrincipalName = 'REPLACE_WITH_MICROSOFT_USER_ID_OR_UPN';
request.driveId = 'REPLACE_WITH_DRIVE_ID';
request.itemId = 'REPLACE_WITH_ITEM_OR_PARENT_ID';
request.recipients = 'recipient@example.com';
request.roles = 'read';
request.requireSignIn = true;
request.sendInvitation = false;
request.retainInheritedPermissions = true;

List<Apptigent.MSGraphDrivePermission> results =
    Apptigent.AddOneDriveLibraryItemPermissions.addPermissions(
        new List<Apptigent.AddOneDriveLibraryItemPermissions.AddOneDriveLibraryItemPermissionsInput>{ request }
    );

System.debug(results.size());

The example leaves exception handling, authorization setup, and presentation or persistence of the result to the calling application.

Use in a Lightning Web Component

Use addOneDriveLibraryItemPermissions from msOneDriveConnectorLib, through MSOneDriveConnectorController. These repository c/ imports apply to an LWC in the same namespace. Complete connector authorization before use.

Pass the selected Connector record ID as the second JavaScript argument. The controller forwards it through the action’s internal overload. The public internal Apex overload is not the global subscriber API shown above.

oneDriveActionExample.js

import { LightningElement } from 'lwc';
import { addOneDriveLibraryItemPermissions, MSOneDriveObjects } from 'c/msOneDriveConnectorLib';

export default class OneDriveActionExample extends LightningElement {
    connectorId = 'REPLACE_WITH_CONNECTOR_RECORD_ID';
    result = null;
    errorMessage = '';
    isRunning = false;
    completed = false;

    async handleRun() {
        if (this.isRunning || this.completed) {
            return;
        }
        this.isRunning = true;
        this.errorMessage = '';
        try {
            const request = MSOneDriveObjects.inputs.addOneDriveLibraryItemPermissions();
            request.userIdOrPrincipalName = 'REPLACE_WITH_MICROSOFT_USER_ID_OR_UPN';
            request.driveId = 'REPLACE_WITH_DRIVE_ID';
            request.itemId = 'REPLACE_WITH_ITEM_OR_PARENT_ID';
            request.recipients = 'recipient@example.com';
            request.roles = 'read';
            request.requireSignIn = true;
            request.sendInvitation = false;
            request.retainInheritedPermissions = true;
            const result = await addOneDriveLibraryItemPermissions(request, this.connectorId);
            if (!Array.isArray(result)) {
                throw new Error('The action did not return a usable result.');
            }
            this.result = result;
            this.completed = true;
        } catch (error) {
            this.errorMessage = error.requiresInteractiveAuthorization
                ? 'Sign in to Microsoft for the connector, then try again.'
                : error.message || 'The OneDrive action failed.';
        } finally {
            this.isRunning = false;
        }
    }
}

oneDriveActionExample.html

<template>
    <lightning-button label="Run action" onclick={handleRun}
        disabled={isRunning}></lightning-button>
    <p role="alert">{errorMessage}</p>
</template>

The library resolves to a flat array, without an outer Apex list.

The controller exposes id, rolesCsv, identity display names, and rawJson. Its link fields do not overcome the model limitation described above; do not assume result.linkWebUrl is populated.

For delegated sign-in, use getOneDriveAuthorizationState, beginOneDriveAuthorization, and createOneDriveOAuthMessageHandler. The example only reports errors. This controller path exposes structured requiresInteractiveAuthorization errors.

The example avoids repeating a completed operation. Reset completed only when starting another deliberate operation. If an error leaves the outcome uncertain, inspect the item or destination before retrying. For Copy, completed means the request returned, not that the background copy has finished.

Error handling and troubleshooting

Symptom	What to check
Required fields error	Provide a nonempty request list with a non-null first item and the required identifiers. Supply the user for non-delegated connectors.
Authorization or access denied	Check connector selection, Microsoft sign-in, consent, permission type, and access to the drive or item.
Resource not found	Verify driveId, itemId, and any version or permission ID. Keep related IDs associated with their source drive.
Missing fields or items	Check Select, item type, mapping limitations, and first-page behavior. Empty results and omitted fields are not proof that a resource does not exist.
Unexpected connector	Review the connector selection limitation above and the Microsoft 365 Flow default.
Operation rejected	Inspect the Microsoft error, item state, library capability, and tenant policy. Handle exceptions or structured Result failures in the caller.