---
title: "Replace a SharePoint connection's site policy"
method: PUT
path: "/v1/integrations/accounts/{account_id}/scope"
tags: ["integrations"]
---

# Replace a SharePoint connection's site policy

`PUT /v1/integrations/accounts/{account_id}/scope`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/integrations/accounts/{account_id}/scope`
- Auth: HTTP bearer

Replaces the WHOLE policy — the complete set of sites this connection may reach, never a delta. ``expected_policy_version`` is a compare-and-set guard: send the version the read returned, or omit it to assert there was no policy at all. Either expectation failing is a 409, and the way forward is to re-read and decide against what the policy now says rather than to resend this one. A selection that cannot become a policy is a 422 naming the entry that refused. Authority is the same rule as the read.

**Send sites only.** The document libraries under them are enumerated here, from the selection, because a ``drive -> site`` pair is what admits a call rooted at a drive and a client that could state one would be granting itself reach. That enumeration is live: if it cannot be finished the previous policy is left exactly as it was and the answer is a 503, because a policy naming a site with none of its libraries admits the site and refuses every document in it.

## Path parameters

- `account_id` string, uuid, required

## Headers

- `X-Tenant-Id` string, nullable

## Request body

- SharePointScopeBody: Replace a SharePoint connection's WHOLE site policy. Whole-set, never a delta: a policy is the complete answer to "which sites may Patricia address through this connection", so the request that sets it says the whole answer. A delta protocol could be made concurrency-safe too, with its own removal grammar; this one is simply the shape that needs no such grammar, and the version check below is what makes it safe. ``expected_policy_version`` is the compare-and-set guard, and omitting it is an EXPECTATION rather than a bypass — it means "I read no policy", so against a connection that already has one the write is refused. That is the direction that cannot silently discard somebody's choice. **Only sites are sent.** The stored policy also names the drives under them, and those are enumerated server-side from the selection rather than accepted here: a ``drive -> site`` pair is what admits a call rooted at a drive, so a client able to state one could name a drive under a site it holds and reach a library on a site it does not. The read still returns the pairs, which is what makes the stored policy inspectable.
  - `mode_code` 'unrestricted' | 'selected_sites', required: Which SharePoint sites a connection may address through Patricia. - ``UNRESTRICTED``: anything the Microsoft identity and the reviewed tool surface permit. This is what every connection does today, and what a migration-backfilled row records. - ``SELECTED_SITES``: only the canonical site ids named in the policy, and the drive ids materialized under them. The mode alone never decides access. A row's ``owner_authored_at`` says whether a HUMAN chose the policy or a landing insert merely recorded that the connection exists, and only the former is a grant.
  - `sites` string[]
  - `expected_policy_version` integer, nullable

## Response `200`

Successful Response

- SharePointScopeResponse: One connection's policy, and the version the next write has to send back. ``policy_version`` is ``None`` when no policy row exists, which is the expect-absent case rather than version zero — an editor has to be able to say "I read no policy" and have that be checkable against the row that does or does not appear. ``owner_authored`` is what makes a row a grant. A row written by the connection-landing insert carries ``false`` here: it records that the connection exists, never that anybody chose its policy, and the authorizer reads that rather than ``mode_code``.
  - `mode_code` 'unrestricted' | 'selected_sites', required: Which SharePoint sites a connection may address through Patricia. - ``UNRESTRICTED``: anything the Microsoft identity and the reviewed tool surface permit. This is what every connection does today, and what a migration-backfilled row records. - ``SELECTED_SITES``: only the canonical site ids named in the policy, and the drive ids materialized under them. The mode alone never decides access. A row's ``owner_authored_at`` says whether a HUMAN chose the policy or a landing insert merely recorded that the connection exists, and only the former is a grant.
  - `policy_version` integer, nullable, required
  - `owner_authored` boolean, required
  - `sites` string[], required
  - `drives` ScopeDrivePair[], required
    - `drive` string, required
    - `site` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)