Skip to main content
Browse documentation

Guide

Connect SharePoint

Sync SharePoint document libraries through Microsoft 365, choose which ones Moira Connect reads, and download their files.

On this page
  1. What you get
  2. Prerequisites
  3. Set up the Microsoft app
  4. Get the capabilities enabled
  5. Connect the account
  6. Choose libraries
  7. Read files
  8. Download a file
  9. Write files
  10. Deselect a library
  11. Limits
  12. Troubleshooting
  13. Next step

What you get

SharePoint is part of the microsoft provider: the same Entra app, account and /v1/files routes as OneDrive, and the same file events, plus drive.library.removed. Four capabilities add it:

  • sites.read finds the sites the account follows or can search.
  • drive.library.read reads the metadata of the libraries you select. Like sites.read, it needs Sites.Read.All.
  • drive.library.download copies a file's content on request. See Download a file.
  • drive.library.write creates, changes, deletes and shares items. It needs Sites.ReadWrite.All. It also needs the matching drive.file.* capability, and sharing needs drive.permission.manage.

Sync reads metadata only: names, sizes, locations and modified times. File contents are downloaded only when your app requests a file, and never uploaded. Sharing is not read from SharePoint: a file lists only grants made through the API.

Prerequisites

  1. A Moira Connect project, selected in the console, and a server API key. accounts:read is enough for listing files; selecting libraries and writing need accounts:write. See API keys.
  2. A Microsoft 365 work or school account. Personal accounts have no SharePoint and report unsupported.
  3. Permission to register an app in Microsoft Entra, and an administrator who can approve the Sites permissions.
  4. The SharePoint capabilities enabled for your project, and a signed-in user who follows the site or can find it by search.

Set up the Microsoft app

SharePoint uses your project's Microsoft app. See Provider credentials.

  1. In the console, open Provider Apps and choose Microsoft 365. Copy the redirect URI, which ends in /oauth/callback/microsoft. Ignore the Outlook callback URI.
  2. In the Microsoft Entra admin center, register an app with a multitenant account type. Add personal accounts only for personal OneDrive.
  3. Under Authentication, add a Web redirect URI.
  4. Under Certificates & secrets, create a client secret and copy its Value, not its ID. Entra shows it once.
  5. Under API permissions, choose Add a permission, Microsoft Graph, Delegated permissions. Add Sites.Read.All, and Sites.ReadWrite.All only if you will write. Also add the permissions that are always requested: Calendars.ReadWrite, Tasks.ReadWrite, Files.ReadWrite, openid, profile and offline_access.
  6. Select Grant admin consent for your tenant. This covers your own tenant only: an administrator of another organization has to approve the app for it.
  7. In Provider Apps, enter the Application (client) ID and the secret Value.
  8. Clear the saved scope list. A saved Scopes and Permissions list is used in place of the scopes of the services you tick (the sign-in scopes are still added), Select Clear all, then choose Save credentials.

For a configured app, choose Replace credentials, enter the Application (client) ID and a secret Value again (create a new secret if you lost the Value), select Clear all, then choose Save replacement. This applies to every Microsoft connection in the project. Connected accounts keep their consent until they reconnect.

Get the capabilities enabled

The four SharePoint capabilities are entitlement-gated. A Moira operator grants each one to your project. Moira Connect marks these capabilities with a Plan badge. Ask through Contact sales, naming your project. There is no self-service request.

Choose services in Connect account lists each capability as enabled or not yet enabled. GET /v1/accounts/{id}/capabilities returns a state per capability: not_granted means no entitlement, not_selected means it is not in your selections, and pending_consent means the account has not approved it yet.

A capability is granted for an account when it is enabled for your project (where it is gated), selected, and approved on the consent screen.

Connect the account

  1. Open Connect account and choose Microsoft.
  2. Enter an Account reference, your own label for the connection. Give each account its own reference: a reference that is already in use points at the account that has it instead of creating another one. Reusing the reference of a ready account completes with no new consent, so newly ticked services stay pending_consent; reconsent instead.
  3. Under Choose services, tick sites.read and drive.library.read in the Drive group, and drive.library.write or drive.library.download only if you need them. An Admin consent badge marks capabilities that usually need administrator approval, and an Included badge marks capabilities that are always requested and cannot be unticked.
  4. The Requested OAuth scopes panel is a preview: a saved scope list replaces it, and the sign-in scopes are still added. Microsoft's consent screen describes permissions in plain language rather than by scope name.
  5. Select Connect Microsoft. The console opens the consent in a new tab and shows Connection started.

To change the services of a connected account, update the selections and ask for a new consent. Both calls need accounts:write and an Idempotency-Key header.

PUT /v1/capability-selections replaces every selection of its scope, the whole project unless you pass account_id. A missing row is handled differently: for a reconsent a capability without a row returns to its default, and a new connection that does not name its capabilities requests only the project's enabled selections, so a project-wide list must name every capability you want. This example is for one account:

bash
curl -X PUT https://api.moiraconnect.com/v1/capability-selections \
  -H "Authorization: Bearer $MOIRA_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data '{"provider":"microsoft","account_id":"<ACCOUNT_ID>","selections":[
    {"capability":"sites.read","enabled":true},
    {"capability":"drive.library.read","enabled":true}]}'

POST /v1/accounts/{id}/reconsent returns a url: open it and finish the consent. Its body must hold at least one of success_redirect_url, webhook_id or opener_origin, or the request fails with a 422 and the code completion_target_required. In the console, Reconnect / adjust services on the account page does the same.

Choose libraries

Discovery is attempted with each account sync. It runs at most every 6 hours after a success and 1 hour after a failed or partial run. The first run is at the first sync after sites.read is granted. In the console, tick a library in the SharePoint libraries panel of the account page.

GET /v1/drives?account_id=$ACCOUNT_ID&limit=50 returns the account's drives (abridged):

json
{
  "data": {
    "items": [
      { "id": "5b1c0c8e-0000-4000-8000-000000000003", "kind": "library",
        "drive_ref": "b!example-graph-drive-id", "site_display_name": "Contoso Intranet",
        "display_name": "Policies", "selected": false, "status": "active", "last_error": null }
    ],
    "next_cursor": null
  }
}

limit is 1 to 100 on this route, and a value outside it is a 422.

Select a library with PATCH /v1/drives/{id} and {"selected": true}. It must be active, and drive.library.read must be granted. The library is read at the next account sync.

Read files

GET /v1/files?account_id=$ACCOUNT_ID&drive=$DRIVE_REF&limit=50 lists files, newest provider_modified_at first, folders included. drive_ref is the value of the drive filter, and default is the personal drive. The response has data.items and data.next_cursor, and limit is clamped to 1 to 100. GET /v1/files/{id} returns one file by its UUID id.

  • Without drive, the list holds the personal drive and the selected libraries.
  • A library file's provider_file_id combines the drive and the item: use it as returned to name a parent folder.
  • A library file is visible only while drive.library.read is granted and its library is selected and active. Otherwise its id returns 404 file_not_found.

Sync changes arrive as drive.file.upserted and drive.file.deleted events that carry drive_ref. A delete made through the API emits drive.file.deleted without drive_ref. A removed library emits one drive.library.removed event (with drive_id and files_trashed), and a share made through the API emits drive.permission.created.

Download a file

POST /v1/files/{id}/content copies a file into your media store. It needs an Idempotency-Key, the literal accounts:read and media:write scopes, a selected library, and drive.library.read and drive.library.download granted. GET needs accounts:read and a literal media:read. On existing accounts, ask your operator for the drive.library.download entitlement, select it, and reconsent only if it is pending_consent. A folder, OneNote notebook or shortcut is 422 file_not_downloadable. After a malware scan, drive.file.content_ready fires and GET /v1/files/{id}/content returns a download_url. The copy is deleted after 24 hours.

Write files

  • You need drive.library.write and the matching drive.file.* capability: drive.file.create, drive.file.update (rename or move) or drive.file.delete, on by default for Microsoft.
  • Sharing with POST /v1/files/{id}/permissions also needs drive.permission.manage, which is off by default: select it, then reconsent.
  • Every write needs an Idempotency-Key header and returns 202 with a command_id.

Create an item with POST /v1/files. It uploads no content:

bash
curl -X POST https://api.moiraconnect.com/v1/files \
  -H "Authorization: Bearer $MOIRA_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data '{"account_id":"<ACCOUNT_ID>","name":"Drafts","drive":"<DRIVE_REF>","parents":["<FOLDER_PROVIDER_FILE_ID>"]}'
  • drive is default or the drive_ref of a selected, active library. Every parent must belong to that library, otherwise the request is a 422.
  • Rename or move with PATCH /v1/files/{id}, delete with DELETE /v1/files/{id}.
  • Without drive.library.write the request is a 403 capability_not_granted and nothing is queued. If the matching drive.file.* capability is off, the command is accepted and then fails with capability_not_granted.

A request body must be a JSON object sent as application/json, or the request fails with invalid_json or unsupported_media_type. See Errors.

Deselect a library

Clear the checkbox in the console, or send PATCH /v1/drives/{id} with {"selected": false}. The library stops syncing and its files leave /v1/files. The personal drive refuses any change with 409 personal_drive_always_selected.

Limits

  • No file content is uploaded.
  • Discovery reads at most 200 sites and 100 libraries per site.
  • The account syncs about every 15 minutes.
  • A removed file stays in the list with trashed: true. A library with a permanent error such as 403 is inaccessible (see last_error); one that no longer exists is removed and its files are trashed.

Troubleshooting

  • The consent screen asks for administrator approval. See step 6 of Set up the Microsoft app, or sign in as the administrator during the connection.
  • 409 entitlement_required. The request named only SharePoint capabilities and the project holds no entitlement. The 409 for a connection created through the API appears when the connect link is opened. A reconsent returns a JSON 409. Connect account in the console does not trigger it. Reconnect / adjust services can, if your selections turn off every capability except the SharePoint ones.
  • The consent screen does not mention SharePoint sites. The capabilities are not enabled, or a saved scope list replaces the ticked services' scopes.
  • GET /v1/drives lists only the personal drive. sites.read is not granted, the user follows no site and search finds none, or discovery has not run yet. Check the capability states: not_selected means tick it and reconnect, pending_consent means reconsent, and unsupported means a personal account.
  • Selecting a library fails. 403 capability_not_granted means drive.library.read is not granted. 409 drive_not_selectable means the library is inaccessible or removed: read last_error. A new selection lists no files until the next sync.

Next step

Select one small library and compare its files with SharePoint first.