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.
| Integration | graph |
|---|---|
| Connection mode | Microsoft Graph |
| Identities | The signed-in user (on-behalf-of), or the project (app-only) |
| Default approver | Set in Admin › Integrations |
| Default sensitivity | Medium |
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.
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.
| Scope | Identity | Grants | Example call |
|---|---|---|---|
user:read | User | The signed-in user's profile | GET /v1.0/me |
files:read | User | Files the user can open, including Excel workbooks | GET /v1.0/shares/{id}/driveItem/workbook/... |
files:write | User | Writing to files the user can edit | PATCH /v1.0/drives/{drive}/items/{item}/... |
lists:read | User | SharePoint list items the user can see | GET /v1.0/sites/.../lists/{list}/items |
lists:write | User | Writing list items | POST /v1.0/sites/.../lists/{list}/items |
mail.send | User | Sending mail as the signed-in user only (another sender is refused) | POST /v1.0/me/sendMail |
mail.send:owner | Project | Mail from and to the project owner only | POST /v1.0/users/{owner}/sendMail |
sites.selected:<site>:read | Project | Reading one SharePoint site and its lists | GET /v1.0/sites/contoso.sharepoint.com:/sites/Procurement:/lists/... |
sites.selected:<site>:write | Project | Writing to one site | |
files.selected:*:read | Project | Reading individual files granted to the app | Snapshot 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/meand below (signed-in user only;GETonly, exceptPOST /v1.0/me/sendMail)/v1.0/shares/{id}/driveItemand below/v1.0/drives/{drive}/items/…and/v1.0/drives/{drive}/root…/v1.0/sites/…POST /v1.0/users/{user}/sendMail
Microsoft Graph permissions (admin consent)
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
- Sign in as an Org Admin and open Admin › Integrations.
- 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.
- Open Admin › Policies and review the built-in rules. "Graph read of the user's own files: auto" approves
user:read,files:readandlists:readas the user, and "Mail from an app to its owner: auto" approvesmail.send:owner. Turn either off if you want every request reviewed. - 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:
- Open the project's Integrations page. Under Data sources, each file shows how many viewers can't open it today.
- Select Show data to everyone with app access and add a one-line purpose.
- 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."
- 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
- Open the project's Integrations page and check Grants in effect lists
graphwith the expected scopes and identity. - 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_DENIEDerror, not someone else's data. - Check Recent calls for the Graph operations, status and whether the answer was cached.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
M365_ACCESS_DENIED for some viewers | They can't open the file in Microsoft 365 | Share the file with them, or use Show data to everyone with app access. |
TC_GRAPH_PATH_NOT_ALLOWED | The path isn't in the gateway's allowlist | Use one of the allowed paths above, or the SDK helpers. |
TC_NO_USER on /v1.0/me | A job called /me; jobs run as the app | Address the site or file directly. |
ACCESS_DENIED on mail from a job | As the app, mail may only go from and to the project owner | Send from and to TC_PROJECT_OWNER_EMAIL. There is no broader mail scope for the app identity today. |
| Stale data for up to a minute | The gateway caches Graph GET responses for 60 seconds | Expected. For large or busy workbooks, snapshot into the project database. |
Intermittent 429 or 503 from Graph | Throttling | The gateway retries with backoff. Reduce call volume or snapshot the data. |