SharePoint

​

Required Scopes

• Sites.Read.All
• Files.Read.All
• User.Read
• offline_access
• User.ReadBasic.All (optional - for including organization users in the Permissions Sync)
• GroupMember.Read.All (optional - for including group membership in the Permissions Sync)
• Sites.FullControl.All (optional - for including sharing and permission changes in real-time webhook updates)

Using Permissions API?

When using Permissions API, SharePoint requires Sites.Read.All, Files.Read.All, User.ReadBasic.All, and GroupMember.Read.All to be configured as Application Permissions (not Delegated Permissions) in your Azure AD app registration. If you enable real-time webhook updates, also add Sites.FullControl.All as an Application Permission. This requires certificate-based authentication and admin consent.Follow the SharePoint: Using Application Permissions setup guide before enabling a sync.After following these steps, verify that you have added Sites.Read.All as both a Microsoft Graph and as a SharePoint scope:

​

Synced Objects

• Files
• Permissions

​

Files

• Site Sync: All files in the specified SharePoint site will be synced.
• Folder Sync: Only files in the specified folder will be synced (recursively including all subfolders by default).
• Sync of specific files: Only a group of specific files will be synced.

{
    "integration": "sharepoint",
    "pipeline": "files",
    "configuration": {
        "siteId": "contoso.sharepoint.com,12345678-1234-1234-1234-123456789012,87654321-4321-4321-4321-210987654321"
    }
}

{
    "integration": "sharepoint",
    "pipeline": "files",
    "configuration": {
        "folderId": "01ABCDEF2345GHIJKL/XYZ1234567890!123",
        "siteId": "contoso.sharepoint.com,12345678-1234-1234-1234-123456789012,87654321-4321-4321-4321-210987654321"
    }
}

{
    "integration": "sharepoint",
    "pipeline": "files",
    "configuration": {
        "fileIds": ["01ABCDEF2345GHIJKL/XYZ1234567890!456"]
    }
}

​

Real-time updates with webhooks

{
    "integration": "sharepoint",
    "pipeline": "files",
    "configuration": {
        "siteId": "contoso.sharepoint.com,12345678-1234-1234-1234-123456789012,87654321-4321-4321-4321-210987654321",
        "useWebhooks": true
    }
}

• File changes: When a file in the Sync’s scope is created, updated, or has its content changed, Paragon updates the synced record and emits the corresponding record_created or record_updated webhook without waiting for the next Incremental Sync.
• Sharing and permission changes: When a file is shared or unshared, Paragon updates the file’s access rules so that Permissions API checks reflect the change in near real time.
• Group membership and directory changes: When users are added to or removed from a Microsoft 365 group referenced in a file’s permissions, or when users join or leave the organization, Paragon updates the affected permission relationships.

• Scheduled Incremental Syncs are disabled. Changes arrive through change notifications instead.
• Periodic Full Syncs continue to run (every 24 hours by default) to catch any changes missed by notifications.
• If a Sync is disabled and later re-enabled, Paragon re-establishes the change notification subscriptions automatically.
• Sharing and permission change notifications require the optional Sites.FullControl.All scope. Real-time group membership and organization directory updates also use the optional GroupMember.Read.All and User.ReadBasic.All scopes.

​

File metadata

• fullPath (always included): The file’s full path within its drive, built from the parent folder path and file name (for example, /drives/<driveId>/root:/Shared Documents/Reports/Q1.pdf). Use this when you need to display or reason about the location of a file in SharePoint without traversing the folder hierarchy yourself.
• metadata (included when includeMetadata is true): A flat object of the file’s SharePoint list item fields, including built-in columns and any custom columns defined on the document library. This is fetched per file using the Microsoft Graph listItem endpoint, so enabling it adds an extra API call per synced file.

{
  "id": "...",
  "externalId": "01ABCDEF2345GHIJKL/XYZ1234567890!123",
  "name": "Q1-Report.pdf",
  "mimeType": "application/pdf",
  "customFields": {
    "fullPath": "/drives/b!.../root:/Shared Documents/Reports/Q1-Report.pdf",
    "metadata": {
      "Title": "Q1 Financial Report",
      "Department": "Finance",
      "ReviewStatus": "Approved",
      "Modified": "2024-04-01T10:00:00Z"
    }
  }
}

​

Choosing Files and Folders

let picker = new paragon.ExternalFilePicker("sharepoint", {
    onFileSelect: (files) => {
        // Handle file selection
    }
});

// Loads external dependencies and user's access token
await picker.init();

// Open the File Picker
picker.open();

// Target a site by URL
await picker.init({
  siteUrl: 'https://contoso.sharepoint.com/sites/Engineering',
});

// Or target a site by ID (resolved via Microsoft Graph)
await picker.init({
  siteId: 'contoso.sharepoint.com,191d8a17-0000-0000-0000-000000000000',
});

picker.open();