SharePoint

What it does

The SharePoint integration lets Speedwave read and edit the files, pages, and lists on one SharePoint site through Microsoft Graph. You pick the site when you connect it, and Speedwave stays inside that site for the life of the integration: it can upload a document, publish a page, or add a list column, but it has no path to any other site in your tenant.

What Speedwave can do

Speedwave has 28 tools here, covering files, pages, lists, and identity. None take a site parameter: every call uses the site_id baked into the worker. Destructive tools cannot be undone.

Tool	What it does
listFileIds	Lists files and folders under a path (defaults to the site root).
getFileFull	Reads a file’s full metadata, with content loaded on demand.
downloadFile	Downloads a SharePoint file to a local path under /workspace.
uploadFile	Uploads a local file to a SharePoint path; supports expectedEtag, createOnly, or overwrite to control conflicts.
listPages	Lists the site’s pages.
getPage	Reads a page’s layout and content.
createPage	Creates a new page.
updatePage	Replaces a page’s full layout (Graph has no partial update).
addWebPart	Adds one of 13 standard web part types to a page.
updateWebPart	Updates an existing web part’s data.
removeWebPart	Removes a web part from a page.
publishPage	Publishes a draft page so it becomes visible.
addImageWebPart	Adds an image web part from an image already uploaded to the site.
generateTableOfContents	Scans a page’s headings and builds a linked list from them.
listLists	Lists the site’s lists.
getList	Reads a list’s definition.
createList	Creates a new list. Needs Sites.Manage.All.
updateList	Renames or reconfigures a list.
deleteList	Deletes a list. Destructive.
addListColumn	Adds a typed column to a list. Needs Sites.Manage.All.
removeListColumn	Removes a column from a list. Destructive.
listItems	Lists items in a list, with optional OData $filter.
getItem	Reads a single item.
createItem	Creates a new item.
updateItem	Updates an existing item.
deleteItem	Deletes an item. Destructive.
deletePage	Deletes a page. Destructive.
getCurrentUser	Returns the id, display name, email, and user principal name of the signed-in account.

Local paths for downloadFile and uploadFile must resolve under /workspace, and a denylist blocks .git, .env, .speedwave, .ssh, .npmrc, .docker, and .kube inside it.

What it consists of

A SharePoint worker runs in its own container, holding two files mounted read-only at /tokens/: an access token and the site ID it is bound to. A host-side OAuth worker owns the longer-lived credentials, client ID, tenant ID, and refresh token, in a project-scoped file the container never mounts. If either mounted file is missing or empty, the worker starts with no client and the integration stays inactive rather than failing loudly.

• Directory~/.speedwave/oauth/<project>/

  • sharepoint.json host-only OAuth state: clientId, tenantId, refreshToken
• Directory/tokens/ mounted read-only into the worker

  • access_token
  • site_id

How it works

Sign-in happens once, through an OAuth device-code flow. You authorize the app in a browser, and Speedwave stores the resulting tokens on the host. The host-side OAuth worker then keeps the SharePoint worker supplied with a fresh access token, so the container never sees the refresh token. The worker refreshes proactively near expiry and reactively on a Graph 401, and every tool call carries the worker’s own site_id from /tokens/site_id.

flowchart LR
  A[SharePoint worker] -->|needs fresh token| B[Host OAuth worker]
  B -->|refresh_token| C[Microsoft /oauth2/v2.0/token]
  C -->|new access_token| D["/tokens/access_token"]
  D -->|re-read| A

Set it up

Connecting SharePoint needs an Azure AD app registration. Follow the general integration flow in connect an integration, then come back here for three SharePoint-specific values: client_id, tenant_id, and site_id.

site_id must be a Microsoft Graph site ID, not a browser URL, so use one of these two forms.

Path form

site_id

acme.sharepoint.com:/sites/Marketing:

Note the colon at the start and the colon at the end.

Composite form

site_id

{hostname},{site-guid},{web-guid}

1. Open Settings and find the SharePoint integration card.
2. Enter client_id, tenant_id, and site_id.
3. Start the connection. Speedwave runs the device-code flow and shows a device code and a Microsoft URL.
4. Open the URL, enter the code, and sign in with an account that has access to the site. Approve the requested permissions.
5. When sign-in finishes, Speedwave writes the tokens to the host and the SharePoint worker becomes available.

Service integrations my my-project

servicestatusveron

githubrunningconfigured

gitlabrunningconfigured

slackconfigure →—

Admin consent

The integration requests Sites.Manage.All, Files.ReadWrite.All, User.Read, and offline_access. Sites.Manage.All is required for creating lists and usually needs a tenant administrator to grant admin consent in Azure AD. Without it, list creation fails.

Security boundaries

Speedwave works through Microsoft Graph only, and only against the site the worker was bound to at setup. It cannot edit site navigation, since Microsoft Graph does not publish those endpoints, so navigation changes stay in the SharePoint UI. The container never holds the refresh token, only a short-lived access token it cannot renew on its own. For where these files live and why each worker only ever sees its own service’s credentials, see how credentials are handled.