Admin permissions: delegated, app-only and Sites.Selected
SPSync reads SharePoint through Microsoft Graph using one multi-tenant Entra ID app (unless you bring your own). You consent to it; nobody creates an app registration by hand. This page explains what each mode of consent grants, who has to grant it, and how to pick the right one.
If you would rather hand your tenant admin a document specific to your setup, pre-filled with your tenant name, the app’s client id, and the exact sites and lists you picked, with copy-paste grant commands using your real ids. The app generates one (Markdown or PDF) from the Admin permissions pack card on the Connect screen for an existing connection. It covers the same ground as this page in more concrete form, and is what most admins should read instead of this one.
Delegated vs app-only
Section titled “Delegated vs app-only”| Delegated (default) | Application (Selected) | |
|---|---|---|
| Runs as | You, using your own SharePoint access | Your own app registration, unattended |
| Who consents | You, for yourself | A tenant admin, once per site or list |
| Sync interval floor | 5 minutes | 1 minute (30 seconds absolute minimum) |
| Keeps running when you’re away | No, it stops when your refresh token expires (about 90 days idle) | Yes |
| Good for | Trying SPSync, personal or small-team use | Scheduled/unattended replications, production |
Start delegated. Move to application permissions once you need syncing to keep running when
nobody is signed in: either on SPSync’s shared app (an admin consents to Sites.Selected
and grants named sites, then the setup screen switches the connection to application mode),
or on your own app when
your policies only allow apps registered in your tenant.
The commands, consent URL and grant steps are on
Connect to SharePoint.
Delegated consent
Section titled “Delegated consent”spsync auth login --client-id <client-id> asks you to consent to:
Sites.Read.All: read SharePoint sites, lists, and libraries you already have access to. SPSync never gets more access than you have.User.Read: your own profile, to show who is signed in and to resolve the person/lookup columns that reference SharePoint users.offline_access: a refresh token, so you are not asked to sign in again every few minutes.
Any user in the tenant can grant this to themselves; it does not need an admin, unless your tenant has admin-consent-required turned on for all apps (a tenant-wide Entra policy, not something SPSync sets).
Application permissions (for unattended sync)
Section titled “Application permissions (for unattended sync)”This is the part that needs a tenant admin, and it is kept narrow on purpose: SPSync never asks for tenant-wide write access, and prefers the smallest possible grant for the job. From narrowest to broadest:
Lists.SelectedOperations.Selected, granted per list. The tightest option: the app can only touch the specific lists an admin names.Sites.Selected, granted per site. The app can read every list and library on that site, but no others.Sites.Read.All(tenant-wide), only if neither of the above is workable for your setup. This is the “read everything” grant and the one security teams tend to push back on. Prefer 1 or 2.
SPSync’s web UI generates an admin-consent URL for whichever scope you choose. If the
signed-in admin has the rights to grant it directly (Sites.FullControl.All, or
Sites.Selected with Full Control/Owner on the site being granted), the in-app helper does
the grant for you. Otherwise, the UI prints the exact PnP PowerShell command for your admin
to run instead. Nothing here requires giving SPSync itself elevated rights to make the
grant, only the rights being granted.
Heads up: granting Lists.SelectedOperations.Selected on a single list breaks that
list’s permission inheritance from its parent site. The in-app helper and the printed
PowerShell both say so before you run them.
Bring your own app
Section titled “Bring your own app”If your organisation requires every third-party integration to use its own app registration, or you need unattended sync, register an Entra app in your tenant with the permissions above and authenticate with a client certificate or secret. A certificate is the better choice. The full steps, including the app registration scripts, certificate creation, site and list grants, and the CLI flags, are on Connect to SharePoint.
Where to look if something fails
Section titled “Where to look if something fails”spsync doctor checks token validity and site grants first. See
Troubleshooting for what its output means.