MS SharePoint – Files – Add Document 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 SharePoint – Files – Add Document Permissions
Category	CloudTools
Apex class and method	AddSharePointLibraryItemPermissions.addPermissions
Input type	AddSharePointLibraryItemPermissions.AddSharePointLibraryItemPermissionsInput
Output type	List<MSGraphDrivePermission>
Authorization	OAuth Delegated (Authorization Code) or OAuth Application (Client Credentials), subject to endpoint restrictions.
Microsoft Graph request	POST /v1.0/sites/{siteId}/drives/{driveId}/items/{itemId}/invite

Prerequisites and permissions

Configure a CloudTools Connector with Connector Type set to Microsoft 365. Complete user sign-in for delegated access. For supported application access, grant application permissions and administrator consent. The calling identity must have access to the relevant site, list, library, or item; tenant policy and resource configuration still apply.

The action permission provider declares the following permission alternatives. These are not cumulative requirements and not all are least privileged. Check the linked Microsoft reference for the endpoint, authorization type, and current restrictions.

Permission type	Declared alternatives
Delegated	Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Application	Files.ReadWrite.All, Sites.ReadWrite.All

See the Microsoft operation and permissions reference.

Inputs

Supply one non-null request with nonblank required identifiers. IDs must belong to the indicated site, list, or drive; do not substitute Salesforce IDs or browser URLs.

Input	Apex field	Type	Required	Description
Site Id	siteId	String	Yes	SharePoint site identifier.
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. Password support is a personal OneDrive feature; do not rely on it for SharePoint.
Retain Inherited Permissions	retainInheritedPermissions	Boolean	No	Keep inherited permissions when sharing for the first time.

The global invocable input does not expose connectorId. Direct subscriber Apex and Flow calls use CloudTools connector selection. Resolve dynamic values before invocation; this action does not resolve replacement tokens.

Outputs

Returns a flat resource list for the first request, or an empty list if no results are mapped. Entries are resources, not one result for each 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: The model exposes id, roles, inheritedFrom, grantedTo, and grantedToV2. It omits link URLs, invitation details, expiration, recipient errors, and grantedToIdentities collections. LWC link fields and rawJson cannot recover these omitted Microsoft properties. A sharing-link request can succeed without exposing its URL.

Use in Flow

Add MS SharePoint – Files – Add Document Permissions in Flow Builder. Use a Microsoft 365 application connector configured as Set as default for Flow automations, supply the required resource IDs, and add fault handling. Delegated connections are not supported for CloudTools Flow automation. This implementation processes only the first input request and is not a bulk operation.

Use in custom Apex

This subscriber-org example uses the Apptigent namespace. Replace the identifiers, configure the connector, and run in a context that permits callouts. Arrange authorization before calling and handle exceptions in the caller.

Apptigent.AddSharePointLibraryItemPermissions.AddSharePointLibraryItemPermissionsInput request =
    new Apptigent.AddSharePointLibraryItemPermissions.AddSharePointLibraryItemPermissionsInput();
request.siteId = 'REPLACE_WITH_SITE_ID';
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;

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

System.debug(results.size());

Use in a Lightning Web Component

Use addSharePointLibraryItemPermissions from msSharePointConnectorLib, through MSSharePointConnectorController. These c/ imports apply to an LWC in the same namespace. The function accepts one request object, including connectorId when applicable.

Connector selection limitation: This action delegates its Graph call to a shared file helper that does not receive the SharePoint request connectorId. It uses default Microsoft 365 connector selection. Supplying connectorId does not guarantee use of that record. Configure and authorize the default connector for this example.

sharePointActionExample.js

import { LightningElement } from 'lwc';
import { addSharePointLibraryItemPermissions, MSSharePointObjects } from 'c/msSharePointConnectorLib';

export default class SharePointActionExample 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 = MSSharePointObjects.inputs.libraryItem();
            request.siteId = 'REPLACE_WITH_SITE_ID';
            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;
            const result = await addSharePointLibraryItemPermissions(request);
            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 SharePoint action failed.';
        } finally {
            this.isRunning = false;
        }
    }
}

sharePointActionExample.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 the outer Apex collection.

The LWC permission object includes rolesCsv and flattened identity names. Its sharing-link fields cannot recover properties omitted by the Apex model.

LWC rawJson serializes the mapped Apex object; it is not the untouched Microsoft response or an additional global invocable output. Use getMSSharePointAuthorizationState, beginMSSharePointAuthorization, and createMSSharePointOAuthMessageHandler to arrange delegated sign-in. The library normalizes controller errors, including requiresInteractiveAuthorization when available; it does not automatically sign in or retry.

The example prevents repeating a completed operation. Reset completed only for a new deliberate operation. If a failure leaves the outcome uncertain, inspect the resource before retrying. For Copy, completed means the request returned, not that the background copy finished.

Error handling and troubleshooting

Symptom	What to check
Required fields error	Supply a nonempty request list, a non-null first request, and the required identifiers or body values.
Authorization or access denied	Check connector selection, sign-in, application versus delegated permissions, administrator consent, and resource access.
Resource not found	Verify the parent site, list, and drive IDs. Distinguish list item IDs from drive item IDs and retain permission or version IDs with their resource.
Missing fields or items	Check query inputs, first-page behavior, supported expansions, item type, and mapped output limitations.
Unexpected connector	Review the connector selection behavior described above and the Microsoft 365 default connector.
Operation rejected	Inspect the Microsoft error, JSON field values, library or page state, supported API capabilities, and tenant policies.