references/graph-permissions.md — Data Room Toolkit

# Microsoft Graph application permissions

The command-line tools use the OAuth 2.0 client-credentials flow and therefore
require application permissions, not delegated user permissions. An
administrator must grant consent.

## Read tools

`dataroom_search.py` and `file_history.py` need read access to drive items and
versions. Use one of these application-permission approaches:

- `Sites.Read.All`
- `Sites.Selected` with a read grant on the intended site

The exact least-privilege permission behavior for drive search, version
history, and default-drive resolution must be verified against Microsoft
documentation.

## Mirror tool

`mirror_dataroom.py` needs read access plus create, replace, and re-download
access for verification. The dry run uses only read requests: it reads the
target drive (`GET /drives/{drive-id}?$select=id,sharePointIds`), each
destination folder (`id`, `name`, `folder`) and each destination item (`id`,
`eTag`, `folder`, `file`). The selected destination must already exist; no
folder above it is inspected or created. Live mode creates only approved
folders beneath it (`POST .../children` with `conflictBehavior=fail`).
A 409/412 on an initial write is a refusal. After an earlier attempt of the
same write, a 409/412, an unretried 5xx or a transport error is outcome unknown
because the write may have completed. Use one of these approaches:

- `Sites.ReadWrite.All`
- `Sites.Selected` with a write-capable grant on the intended site

The current grant roles and administration commands for `Sites.Selected` must
be verified against Microsoft documentation.

## Upload guarantees

Microsoft references below were researched and verified on 1 October 2026:

- [driveItem](https://learn.microsoft.com/en-us/graph/api/resources/driveitem?view=graph-rest-1.0):
  conflictBehavior supports fail, replace and rename; PUT defaults to replace
  and this parameter belongs in the URL, not the body. Creates explicitly use
  fail in the direct PUT URL or the upload-session item body.
- [Direct upload](https://learn.microsoft.com/en-us/graph/api/driveitem-put-content?view=graph-rest-1.0):
  the header table lists Authorization and Content-Type only; If-Match is not
  documented. Accordingly, every replacement uses an upload session.
- [Upload sessions](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession?view=graph-rest-1.0):
  If-Match on session creation returns 412 if the eTag/cTag differs. Item
  conflictBehavior supports fail (default), replace and rename. A name
  conflict during a fail session returns an error at the last range (409
  nameAlreadyExists). DELETE on the upload URL cancels a session (204).
  No final-commit If-Match recheck is documented.

A create never replaces an existing item (documented). Every replace uses an
upload session with `If-Match: <approved eTag>` and is refused if the item
changed before session creation (documented) or before the final byte range
(checked by the tool). A change in the short window between that last check
and Microsoft's commit is not covered by any documented guarantee.
On an eTag mismatch, the tool cancels the session with best-effort DELETE and
reports a failed file. A local byte change likewise cancels the session
instead of sending the final range. Empty replacements are counted as dry-run failures and refused before
approval because there is no final byte range. Live plans containing a
refusal cannot write.

## Consent and scope

Application permissions act without an interactive user and can expose broad
tenant data. Prefer `Sites.Selected` for a data room and grant only the intended
site. Keep the client secret in a secret manager, rotate it according to local
policy, and remove unused grants.

Portal navigation, permission naming changes, Graph upload size limits, upload
session rules, and tenant-specific policies must be verified against Microsoft
documentation before production use.

Upload sessions default to 5 MiB (5,242,880 bytes = 16 x 327,680). Configuration and `--chunk-size` must be positive integer multiples of 320 KiB and strictly less than 60 MiB per request; invalid sizes are refused before authentication or any request. The final range may be shorter. See [Microsoft upload-session requirements](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession?view=graph-rest-1.0).

By Zero Width Lab (zerowidthlab.com)

License: MIT (read it).

Back to the listing