Skip to main content

Microsoft 365

Overview​

The Microsoft 365 integration (graph) gives apps Excel workbooks, SharePoint and OneDrive files, SharePoint lists and Outlook mail through Microsoft Graph. There's no connect screen for users: by default an app reads as the signed-in person, so each viewer sees only what they could already open in Microsoft 365.

Scheduled jobs and shared dashboards can read as the app itself, but only from the specific SharePoint sites or files IT approves.

Integrationgraph
Connection modeMicrosoft Graph
IdentitiesThe signed-in user (on-behalf-of), or the project (app-only)
Default approverSet in Admin › Integrations
Default sensitivityMedium

Prerequisites​

  • A Microsoft 365 tenant, and an Entra ID administrator who can grant admin consent to the vastframe app registration.
  • For app-only access: the SharePoint site owners who will approve access to their sites.
Availability

Locally, a Graph stand-in serves fixture files, lists, file permissions and a mailbox, so every flow on this page works without a tenant. On Azure installations, the on-behalf-of exchange (MSAL) and a per-project app identity for Sites.Selected are planned and not yet available.

Permissions​

vastframe scopes​

These are the scopes projects ask for and IT caps with max scopes.

ScopeIdentityGrantsExample call
user:readUserThe signed-in user's profileGET /v1.0/me
files:readUserFiles the user can open, including Excel workbooksGET /v1.0/shares/{id}/driveItem/workbook/...
files:writeUserWriting to files the user can editPATCH /v1.0/drives/{drive}/items/{item}/...
lists:readUserSharePoint list items the user can seeGET /v1.0/sites/.../lists/{list}/items
lists:writeUserWriting list itemsPOST /v1.0/sites/.../lists/{list}/items
mail.sendUserSending mail as the signed-in user only (another sender is refused)POST /v1.0/me/sendMail
mail.send:ownerProjectMail from and to the project owner onlyPOST /v1.0/users/{owner}/sendMail
sites.selected:<site>:readProjectReading one SharePoint site and its listsGET /v1.0/sites/contoso.sharepoint.com:/sites/Procurement:/lists/...
sites.selected:<site>:writeProjectWriting to one site
files.selected:*:readProjectReading individual files granted to the appSnapshot jobs

The default max scopes for graph are all of the above.

Microsoft Graph paths apps can use​

The gateway refuses any Graph path outside this list, before checking grants:

  • /v1.0/me and below (signed-in user only; GET only, except POST /v1.0/me/sendMail)
  • /v1.0/shares/{id}/driveItem and below
  • /v1.0/drives/{drive}/items/… and /v1.0/drives/{drive}/root…
  • /v1.0/sites/…
  • POST /v1.0/users/{user}/sendMail

Delegated Graph permissions never let an app exceed what the signed-in user can already access. For app-only access, vastframe uses Sites.Selected and per-file permissions instead of tenant-wide permissions. A Graph-backed Org Sync that reads the directory with the application permissions User.Read.All and GroupMember.Read.All (read-only) is planned for Azure installations. See Org chart and Org Sync.

Setup steps​

  1. Sign in as an Org Admin and open Admin › Integrations.
  2. Select Microsoft 365, then configure it:
    • Approvers: people or groups who review Microsoft 365 requests.
    • Max scopes: remove any scope your organization doesn't allow, for example files:write.
    • Data sensitivity: low, medium or high. It's shown on every request.
  3. Open Admin › Policies and review the built-in rules. "Graph read of the user's own files: auto" approves user:read, files:read and lists:read as the user, and "Mail from an app to its owner: auto" approves mail.send:owner. Turn either off if you want every request reviewed.
  4. Save. Changes are audited.

Use it in an app​

// Excel table → array of objects, as the signed-in user
const rows = await tc.m365
.excel('https://contoso.sharepoint.com/sites/Finance/Shared Documents/Budget FY27.xlsx')
.table('Actuals')
.rows();

// SharePoint list items
const vendors = await tc.m365.list('https://contoso.sharepoint.com/sites/Procurement', 'Vendors').items();

// Outlook mail
await tc.m365.mail.send({ to: 'someone@contoso.com', subject: 'Weekly report', html });

Prefer Excel tables over raw ranges: tables stay stable when rows are added. In scheduled jobs the SDK acts as the app automatically, so Graph is limited to the sites and files IT granted, and mail can only go from and to the project owner (TC_PROJECT_OWNER_EMAIL). See the SDK reference.

Show file data to the whole app audience​

Reading as the user means a viewer who can't open Budget FY27.xlsx gets no data. That's the safe default. If the owner wants everyone who can open the app to see the numbers, the app must read with its own identity, which widens access beyond the file's permissions. So it goes through an approval:

  1. Open the project's Integrations page. Under Data sources, each file shows how many viewers can't open it today.
  2. Select Show data to everyone with app access and add a one-line purpose.
  3. The request goes to the owner's manager and the Microsoft 365 approvers, with the facts filled in, for example "budget shows data from Finance/Budget FY27.xlsx to 40 people; 12 of them can't open the file today."
  4. On approval, the project's app identity gets a per-file permission. A snapshot job can then copy the data into the project database for viewers who can't open the file.

Only the project owner or an Org Admin can file this request. Agents can file it with the MCP tool request_grant (share_file).

App-only access to a SharePoint site​

When a job reads a site with no signed-in user, the scan or first call asks for sites.selected:<site>:read. The request is routed to the site's owners as well as the Microsoft 365 approvers. On approval, vastframe grants the project's app identity access to that site only, and jobs that were waiting run again.

Verify​

  1. Open the project's Integrations page and check Grants in effect lists graph with the expected scopes and identity.
  2. Open the app as a user who can open the file, and as one who can't. The second user should get a clear M365_ACCESS_DENIED error, not someone else's data.
  3. Check Recent calls for the Graph operations, status and whether the answer was cached.

Troubleshooting​

SymptomCauseFix
M365_ACCESS_DENIED for some viewersThey can't open the file in Microsoft 365Share the file with them, or use Show data to everyone with app access.
TC_GRAPH_PATH_NOT_ALLOWEDThe path isn't in the gateway's allowlistUse one of the allowed paths above, or the SDK helpers.
TC_NO_USER on /v1.0/meA job called /me; jobs run as the appAddress the site or file directly.
ACCESS_DENIED on mail from a jobAs the app, mail may only go from and to the project ownerSend from and to TC_PROJECT_OWNER_EMAIL. There is no broader mail scope for the app identity today.
Stale data for up to a minuteThe gateway caches Graph GET responses for 60 secondsExpected. For large or busy workbooks, snapshot into the project database.
Intermittent 429 or 503 from GraphThrottlingThe gateway retries with backoff. Reduce call volume or snapshot the data.
Was this page helpful?